version 2 release 3 z/os - ibm...2019/03/28 · understanding delays and hangs in zfs using the zfs...

z/OSVersion 2 Release 3

Distributed File Service zFSAdministration

IBM

SC23-6887-30

Note

Before using this information and the product it supports, read the information in “Notices” on page469.

This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications untilotherwise indicated in new editions.

Last updated: 2019-03-28© Copyright International Business Machines Corporation 2001, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

List of Figures....................................................................................................... ixList of Tables........................................................................................................ xi

About this document...........................................................................................xiiiHow this document is organized............................................................................................................... xiiiConventions used in this document ......................................................................................................... xiiiz/OS information........................................................................................................................................xivReferences to DFS information................................................................................................................. xiv

How to send your comments to IBM......................................................................xvIf you have a technical problem.................................................................................................................xv

Summary of changes...........................................................................................xviSummary of changes for zFS for z/OS Version 2 Release 3 (V2R3) ........................................................ xviSummary of changes for zFS for z/OS Version 2 Release 2 (V2R2).......................................................... xxz/OS Version 2 Release 1 summary of changes.......................................................................................xxii

Part 1. zFS administration guide............................................................................ 1

Chapter 1. Overview of the zFS File System................................................................................................3Features.................................................................................................................................................. 3Terminology and concepts..................................................................................................................... 4What's new or changed for zFS in z/OS V2R3........................................................................................7What's new or changed for zFS in z/OS V2R2........................................................................................7What's new or changed for zFS in z/OS V2R1........................................................................................8

Chapter 2. Installing and configuring zFS................................................................................................. 11zFS installation and configuration steps..............................................................................................11Applying required APARs for z/OS V2R3............................................................................................. 14Specifying zFS file systems as sysplex-aware.....................................................................................14

Using zFS read/write sysplex-aware file systems..........................................................................15Changing the sysplex-awareness of a mounted zFS read/write file system.................................16

zFS running in the z/OS UNIX address space......................................................................................16

Chapter 3. Managing zFS processes..........................................................................................................19Starting zFS...........................................................................................................................................19Stopping zFS.........................................................................................................................................19

Determining zFS status...................................................................................................................20

Chapter 4. Creating and managing zFS file systems using compatibility mode aggregates................... 21Creating a compatibility mode aggregate............................................................................................21Using version 1.5 aggregates and extended (v5) directories..............................................................23

Creating a version 1.5 aggregate....................................................................................................23Converting an existing aggregate to version 1.5............................................................................24Converting an existing v4 directory to an extended (v5) directory............................................... 25Guidelines for v4 to v5 conversion................................................................................................. 25

Growing a compatibility mode aggregate............................................................................................26Dynamically growing a compatibility mode aggregate........................................................................26Creating a multi-volume compatibility mode aggregate.....................................................................27Adding volumes to a compatibility mode aggregate........................................................................... 29Increasing the size of a compatibility mode aggregate...................................................................... 29

Copying each file and directory of the aggregate to a larger data set...........................................30

iii

Copying the physical blocks of the aggregate to a larger data set................................................ 31Encrypting and compressing zFS file system data.............................................................................. 32

The encryption process.................................................................................................................. 33The compression process...............................................................................................................36

Decreasing the size of a compatibility mode aggregate......................................................................39Renaming or deleting a compatibility mode aggregate.......................................................................40Changing zFS attributes on a mounted zFS compatibility mode file system......................................41Unmounting zFS file systems before copying or moving.................................................................... 42Understanding zFS disk space allocation............................................................................................ 43

How data is stored on systems before z/OS V1R13...................................................................... 44Support for type 30 SMF record .................................................................................................... 46

Sharing zFS data in a non-shared file system sysplex........................................................................ 46Minimum and maximum file system sizes...........................................................................................46

Version 1.5 aggregates................................................................................................................... 47Version 1.4 aggregates................................................................................................................... 47v4 directory considerations............................................................................................................ 48

Chapter 5. Using zFS in a shared file system environment.......................................................................49Overview of the shared file system environment................................................................................ 49Read-only mounted file systems......................................................................................................... 49zFS support for read/write file systems with different levels of sysplex-awareness.........................50zFS-enhanced sysplex-aware support................................................................................................ 51zFS ownership versus z/OS UNIX ownership of file systems..............................................................51

Determining the file system owner................................................................................................ 52When is the z/OS UNIX owner important?...........................................................................................53Dynamic movement of the zFS owner................................................................................................. 54Considerations when using zFS in a shared file system environment................................................ 55

Chapter 6. Copying or performing a backup of a zFS................................................................................59Backing up a zFS aggregate................................................................................................................. 60

Restoring an aggregate with DFSMSdss logical restore................................................................ 60

Chapter 7. Migrating data from HFS or zFS to zFS....................................................................................63Using the z/OS HFS to zFS migration tool............................................................................................63Using the z/OS UNIX pax command.................................................................................................... 63

Using an intermediate archive file..................................................................................................64Without using an intermediate archive file.................................................................................... 64

Chapter 8. Performance and debugging................................................................................................... 65Performance tuning..............................................................................................................................65

Total cache size...............................................................................................................................66Metadata cache...............................................................................................................................66Vnode cache....................................................................................................................................66User file cache.................................................................................................................................66Log files........................................................................................................................................... 67Log file cache.................................................................................................................................. 67Fixed storage...................................................................................................................................67I/O balancing...................................................................................................................................67

Monitoring zFS performance................................................................................................................68Resetting performance monitoring data........................................................................................ 69Sample zFS QUERY reports............................................................................................................ 69

Using SMF records to report on activities ...........................................................................................89SMF record type 92.........................................................................................................................89

Debugging aids for zFS.........................................................................................................................91Overview of trace options for zFS...................................................................................................91Understanding the salvager utility................................................................................................. 92Understanding zFS dumps..............................................................................................................93Determining the XCF protocol interface level................................................................................ 94

iv

Saving initialization messages in a data set...................................................................................94Determining service levels............................................................................................................. 94Understanding namespace validation and correction................................................................... 95Understanding delays and hangs in zFS using the zFS hang detector.......................................... 95Identifying storage shortages in zFS............................................................................................100

Diagnosing disabled aggregates........................................................................................................ 101Handling disabled aggregates......................................................................................................101

Chapter 9. Overview of the zFS audit identifier...................................................................................... 103Enabling the zFS auditid.................................................................................................................... 104

Part 2. zFS administration reference.................................................................. 105

Chapter 10. z/OS system commands......................................................................................................107MODIFY ZFS PROCESS...................................................................................................................... 108SETOMVS RESET................................................................................................................................ 115

Chapter 11. zFS commands.................................................................................................................... 117ioeagfmt..............................................................................................................................................118ioeagslv...............................................................................................................................................122ioefsutl................................................................................................................................................127ioefsutl converttov4........................................................................................................................... 128ioefsutl converttov5........................................................................................................................... 130ioefsutl format....................................................................................................................................132ioefsutl salvage.................................................................................................................................. 136MOUNT............................................................................................................................................... 140zfsadm................................................................................................................................................ 143zfsadm aggrinfo..................................................................................................................................147zfsadm apropos..................................................................................................................................150zfsadm attach.....................................................................................................................................152zfsadm chaggr.................................................................................................................................... 155zfsadm compress............................................................................................................................... 158zfsadm config..................................................................................................................................... 160zfsadm configquery............................................................................................................................165zfsadm convert...................................................................................................................................169zfsadm decompress........................................................................................................................... 172zfsadm decrypt...................................................................................................................................174zfsadm define.....................................................................................................................................176zfsadm delete.....................................................................................................................................179zfsadm detach....................................................................................................................................181zfsadm encrypt...................................................................................................................................183zfsadm fileinfo....................................................................................................................................186zfsadm format.................................................................................................................................... 192zfsadm fsinfo...................................................................................................................................... 195zfsadm grow....................................................................................................................................... 205zfsadm help........................................................................................................................................ 206zfsadm lsaggr..................................................................................................................................... 208zfsadm lsfs..........................................................................................................................................210zfsadm lssys....................................................................................................................................... 212zfsadm query......................................................................................................................................213zfsadm quiesce.................................................................................................................................. 216zfsadm setauditfid..............................................................................................................................218zfsadm salvage...................................................................................................................................220zfsadm shrink..................................................................................................................................... 222zfsadm unquiesce.............................................................................................................................. 225

Chapter 12. The zFS configuration options file (IOEPRMxx or IOEFSPRM)...........................................227

v

IOEFSPRM.......................................................................................................................................... 227

Chapter 13. zFS application programming interface information..........................................................239pfsctl (BPX1PCT)................................................................................................................................240Attach Aggregate................................................................................................................................246Change Aggregate Attributes.............................................................................................................249Define Aggregate ...............................................................................................................................252Detach Aggregate...............................................................................................................................256Encrypt (Decrypt, Compress, or Decompress) Aggregate................................................................ 258File Snapshot......................................................................................................................................261Format Aggregate ..............................................................................................................................266Grow Aggregate..................................................................................................................................270List Aggregate Status (Version 1)...................................................................................................... 273List Aggregate Status (Version 2)...................................................................................................... 276List Attached Aggregate Names (Version 1)......................................................................................283List Attached Aggregate Names (Version 2)......................................................................................286List Detailed File System Information............................................................................................... 290List File Information...........................................................................................................................304List File System Names (Version 1)................................................................................................... 312List File System Names (Version 2)................................................................................................... 316List File System Status.......................................................................................................................320List Systems....................................................................................................................................... 328Query Config Option...........................................................................................................................331Quiesce Aggregate............................................................................................................................. 336Reset Backup Flag..............................................................................................................................338Salvage Aggregate..............................................................................................................................341Set Auditfid.........................................................................................................................................343Set Config Option............................................................................................................................... 346Shrink Aggregate................................................................................................................................ 349Statistics Compression Information..................................................................................................352Statistics Directory Cache Information............................................................................................. 356Statistics Iobyaggr Information.........................................................................................................360Statistics Iobydasd Information........................................................................................................ 367Statistics Iocounts Information.........................................................................................................373Statistics Kernel Information.............................................................................................................379Statistics Locking Information...........................................................................................................385Statistics Log Cache Information.......................................................................................................393Statistics Metadata Cache Information.............................................................................................402Statistics Server Token Management Information............................................................................408Statistics Storage Information...........................................................................................................413Statistics Sysplex Client Operations Information............................................................................. 423Statistics Sysplex Owner Operations Information............................................................................ 429Statistics Transaction Cache Information......................................................................................... 435Statistics User Cache Information.....................................................................................................439Statistics Vnode Cache Information.................................................................................................. 449Unquiesce Aggregate......................................................................................................................... 457

Appendix A. Running the zFS pfsctl APIs in 64-bit mode.....................................461Statistics Iocounts Information (64-bit mode).......................................................................................461

Appendix B. Accessibility...................................................................................465Accessibility features.............................................................................................................................. 465Consult assistive technologies................................................................................................................ 465Keyboard navigation of the user interface.............................................................................................. 465Dotted decimal syntax diagrams.............................................................................................................465

Notices..............................................................................................................469Terms and conditions for product documentation................................................................................. 470

vi

IBM Online Privacy Statement................................................................................................................ 471Policy for unsupported hardware............................................................................................................471Minimum supported hardware................................................................................................................472Programming Interface Information.......................................................................................................472Trademarks.............................................................................................................................................. 472

Glossary............................................................................................................ 473Index................................................................................................................ 475

vii

List of Figures

1. z/OS UNIX and zFS file system ownership................................................................................................... 52. Example job to create a compatibility mode file system using IOEFSUTL................................................223. Example job to add volumes to a zFS aggregate........................................................................................294. Sample job to copy each file and directory of an aggregate to a larger data set.......................................305. Sample job to copy the physical blocks of an aggregate to a larger data set............................................316. Copying blocks from a full zFS data set into a larger data set................................................................... 327. Example job to reconcile the file system and aggregate name................................................................. 418. Example job to delete a compatibility mode aggregate.............................................................................419. Allocating disk space (example 1) ............................................................................................................. 4510. Allocating disk space (example 2)............................................................................................................4511. Example of a secondary zfsadm define command.................................................................................. 4712. Sysplex-aware file system (read-only)..................................................................................................... 5013. zFS read/write file systems sysplex-aware and non-sysplex aware on a file system basis. ................. 5114. zFS sysplex-aware file system with new owner....................................................................................... 5215. zfsadm lsaggr and df -v output after mount.............................................................................................5216. D OMVS,F output after mount...................................................................................................................5217. zfsadm lsaggr and df -v output after movement......................................................................................5318. D OMVS,F output after movement............................................................................................................5319. File system ownership when mount fails................................................................................................. 5420. Steps for quiesce and unquiesce..............................................................................................................5921. Job to back up a zFS aggregate................................................................................................................ 6022. Job to restore a zFS aggregate................................................................................................................. 6023. Job to restore a zFS aggregate with replace............................................................................................ 6124. Sample STOR report (part 1 of 2)............................................................................................................. 8325. Sample STOR report (part 2 of 2)............................................................................................................. 8426. Example of how to check whether user tasks are hung.......................................................................... 9827. zFS auditid examples..............................................................................................................................10328. Sample job to create a compatibility mode aggregate and file system................................................ 12129. Job to verify a zFS aggregate that uses debug parameters specified in IOEFSPRM............................ 12630. Job to verify a zFS aggregate that uses debug parameters specified in parmlib member

IOEPRM03 ............................................................................................................................................... 12631. Job to convert a version 1.5 aggregate to a version 1.4 aggregate.......................................................12932. Job to convert a version 1.4 aggregate to a version 1.5 aggregate.......................................................13133. Sample job to create and format a version 1.4 aggregate ....................................................................13534. Job to verify a zFS aggregate using debug parameters specified in IOEZPRM.................................... 13935. Example of zfsadm aggrinfo -long command ........................................................................................14836. Job to attach an aggregate..................................................................................................................... 154

ix

List of Tables

1. Determining sysplex-awareness for zFS read/write file systems.............................................................. 502. DATASET report fields................................................................................................................................. 703. FILE report fields.........................................................................................................................................714. IOBYDASD report fields.............................................................................................................................. 725. LFS report fields.......................................................................................................................................... 776. COMPRESS report fields..............................................................................................................................787. STKM report fields.......................................................................................................................................818. STOR report fields....................................................................................................................................... 859. User File (VM) Caching System Statistics report fields.............................................................................. 8710. Subtypes for SMF record type 92............................................................................................................. 9011. zFS man command examples.................................................................................................................11712. Return codes for -verifyonly that are returned by the salvager.............................................................12213. Return codes for -recoveronly that are returned by the salvager......................................................... 12314. Criteria for selecting aggregates.............................................................................................................19715. Definitions of abbreviated values when the -basic or -owner options are specified............................19816. Statistics displayed when the -owner option is specified..................................................................... 19917. Sorting options when the -sort option is specified................................................................................ 20018. Local statistics displayed when the full option is specified...................................................................20119. Summary of APIs for pfsctl ....................................................................................................................24220. Summary of w_pioctl calls for zFS......................................................................................................... 245

xi

About this document

The purpose of this document is to provide complete and detailed guidance and reference information.This information is used by system administrators that work with the z/OS File System (zFS) component ofthe IBM® z/OS® Distributed File Service base element.

How this document is organizedThis document is divided into parts, each part divided into chapters:

• Part 1, “zFS administration guide,” on page 1 provides guidance information for the z/OS File System(zFS).

• Part 2, “zFS administration reference,” on page 105 provides reference information about z/OS FileSystem (zFS), which includes z/OS system commands, zFS commands, and zFS data sets.

Conventions used in this documentThis document uses the following typographic conventions:

BoldBold words or characters represent system elements that you must enter into the system literally,such as commands.

ItalicItalicized words or characters represent values for variables that you must supply.

Example FontExamples and information displayed by the system are printed using an example font that is aconstant width typeface.

[ ]Optional items found in format and syntax descriptions are enclosed in brackets.

{ }A list from which you choose an item found in format and syntax descriptions are enclosed by braces.

|A vertical bar separates items in a list of choices.

< >Angle brackets enclose the name of a key on a keyboard.

…Horizontal ellipsis points indicated that you can repeat the preceding item one or more times.

\A backslash is used as a continuation character when entering commands from the shell that exceedone line (255 characters). If the command exceeds one line, use the backslash character \ as the lastnonblank character on the line to be continued, and continue the command on the next line.

Note: When you enter a command from this document that uses the backslash character (\), makesure that you immediately press the Enter key and then continue with the rest of the command. Inmost cases, the backslash has been positioned for ease of readability.

#A pound sign is used to indicate a command is entered from the shell, specifically where rootauthority is needed (root refers to a user with a UID = 0).

© Copyright IBM Corp. 2001, 2019 xiii

z/OS informationThis information explains how z/OS references information in other documents and on the web.

When possible, this information uses cross document links that go directly to the topic in reference usingshortened versions of the document title. For complete titles and order numbers of the documents for allproducts that are part of z/OS, see z/OS Information Roadmap.

To find the complete z/OS library, go to IBM Knowledge Center (www.ibm.com/support/knowledgecenter/SSLTBW/welcome).

References to DFS informationInformation about installing Distributed File Service components is found in z/OS Program Directory.

Information about z/OS File System messages and codes is found in z/OS Distributed File ServiceMessages and Codes.

xiv z/OS: Distributed File Service zFS Administration

http://www.ibm.com/support/knowledgecenter/SSLTBW/welcomehttp://www.ibm.com/support/knowledgecenter/SSLTBW/welcome

How to send your comments to IBM

We invite you to submit comments about the z/OS product documentation. Your valuable feedback helpsto ensure accurate and high-quality information.

Important: If your comment regards a technical question or problem, see instead “If you have a technicalproblem” on page xv.

Submit your feedback by using the appropriate method for your type of comment or question:Feedback on z/OS function

If your comment or question is about z/OS itself, submit a request through the IBM RFE Community(www.ibm.com/developerworks/rfe/).

Feedback on IBM Knowledge Center functionIf your comment or question is about the IBM Knowledge Center functionality, for example searchcapabilities or how to arrange the browser view, send a detailed email to IBM Knowledge CenterSupport at [email protected].

Feedback on the z/OS product documentation and contentIf your comment is about the information that is provided in the z/OS product documentation library,send a detailed email to [email protected]. We welcome any feedback that you have, includingcomments on the clarity, accuracy, or completeness of the information.

To help us better process your submission, include the following information:

• Your name, company/university/institution name, and email address• The following deliverable title and order number: z/OS Distributed File Service zFS Administration,

SC23-6887-30• The section title of the specific information to which your comment relates• The text of your comment.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute the commentsin any way appropriate without incurring any obligation to you.

IBM or any other organizations use the personal information that you supply to contact you only about theissues that you submit.

If you have a technical problemIf you have a technical problem or question, do not use the feedback methods that are provided forsending documentation comments. Instead, take one or more of the following actions:

• Go to the IBM Support Portal (support.ibm.com).• Contact your IBM service representative.• Call IBM technical support.

© Copyright IBM Corp. 2001, 2019 xv

http://www.ibm.com/developerworks/rfe/http://www.ibm.com/developerworks/rfe/mailto:[email protected]:[email protected]://support.ibm.com

Summary of changes

This information includes terminology, maintenance, and editorial changes. Technical changes oradditions to the text and illustrations for the current edition are indicated by a vertical line to the left ofthe change.

Summary of changes for zFS for z/OS Version 2 Release 3 (V2R3)The most recent updates are listed at the top of each section.

New

• With APAR OA56145, which added support for backup of zFS file system data on a file basis, thesesections were added or updated.

– A new API, File Snapshot, was added. See “File Snapshot” on page 261.– A new field, backup progress, was added to the -localonly option of zfsadm fileinfo. It

indicates that the file is being backed up and the percentage of completion. The example was alsoupdated. See “zfsadm fileinfo” on page 186.

– Updates were made to zfsadm fsinfo.

- The new BK value shows aggregates that contain files being backed up. See Table 14 on page 197.- The BK value was also added to Table 15 on page 198.- You can also obtain statistics for files that are being backed up. See Table 16 on page 199.

– A new usage note was added to these commands to indicate that you cannot perform them withactive file backups.

- “zfsadm compress” on page 158- “zfsadm decompress” on page 172- “zfsadm decrypt” on page 174- “zfsadm encrypt” on page 183- “zfsadm shrink” on page 222

– Examples were updated for these APIs:

- “List Detailed File System Information” on page 290- “List File Information” on page 304

• With APAR OA55235, clarification was added that, beginning with z/OS V2R3, the DEFINE CLUSTERcommand string contains the ZFS parameter to indicate that the specified VSAM linear set is intended tobe used as a ZFS aggregate. See the usage notes section in “zfsadm define” on page 176.

• Health check ZFS_VERIFY_COMPRESSION_HEALTH was added. It checks whether all user cache pagesare registered with the zEDC Express service when there are compressed file systems. For moreinformation about the health check, see IBM Health Checker for z/OS User's Guide.

• “What's new or changed for zFS in z/OS V2R3” on page 7 was added.• “Applying required APARs for z/OS V2R3” on page 14 was added.• Subcommands that were missing in previous releases were added in the pfsctl section. See the table on

summary of APIs for pfsctl in “pfsctl (BPX1PCT)” on page 240.• VSAM linear data sets that are created on z/OS V2R3 systems with the zfsadm define command or

the Define Aggregate API do not need to be formatted before they are mounted. If IDCAMS is used todefine the VSAM linear sets and the ZFS keyword is used, they also do not need to be formatted beforethey are mounted. When the aggregates are formatted at mount, default values are used for all format

xvi z/OS: Distributed File Service zFS Administration

options. If the IOEFSPRM format_aggrversion option is not specified, the defaults will result in thecreation and mount of a version 1.5 aggregate.

– The -format_perms option was added to “zfsadm config” on page 160 and “zfsadm configquery” onpage 165.

– A new configuration option, format_perms, was added to the IOEFSPRM configuration file. See“IOEFSPRM” on page 227.

– Two new subcommands were added: Query format_perms(267) and Setformat_perms(266). See the ZFSCALL_CONFIG section in the table on summary of APIs for pfsctlin “pfsctl (BPX1PCT)” on page 240.

• zFS has added support for encrypting file system data using the DFSMS access method encryption.Support has also been added for compressing file system data using the zEDC compression method.New file systems can be defined and formatted so that any data added to them are automaticallyencrypted, compressed, or both. For more information, see “Encrypting and compressing zFS filesystem data” on page 32.

– New commands were added:

- “zfsadm compress” on page 158- “zfsadm decompress” on page 172- “zfsadm decrypt” on page 174- “zfsadm encrypt” on page 183

– These commands have new options:

- “ioeagfmt” on page 118- “ioefsutl format” on page 132- “zfsadm config” on page 160- “zfsadm configquery” on page 165- “zfsadm format” on page 192

– New APIs were added:

- “Encrypt (Decrypt, Compress, or Decompress) Aggregate” on page 258- “Statistics Compression Information” on page 352

– These APIs were updated:

- “Define Aggregate ” on page 252- “Format Aggregate ” on page 266- “List Detailed File System Information” on page 290- “List File Information” on page 304- “Statistics User Cache Information” on page 439

– The contents of the VM report was updated. For a sample report, see “VM” on page 86.– New processing options (edc_buffer_pool, format_compression, format_encryption, and

long_cmd_threads) were added to the IOEFSPRM configuration file. The edc_fixed option was addedto user_cache_size. See “IOEFSPRM” on page 227.

• The size of a zFS aggregate can be reduced by releasing space from the associated VSAM data set.

– A new command, zfsadm shrink, was added. See “zfsadm shrink” on page 222.– A new API was added. See “Shrink Aggregate” on page 349. This API can be accessed via a new

subcommand opcode (266).– A new section was added. See “Decreasing the size of a compatibility mode aggregate” on page 39.

• Certain common mount options such as aggrfull and aggrgrow can be changed dynamically without theoverhead of unmounting and remounting the file system.

– A new command, zfsadm chaggr, was added. See “zfsadm chaggr” on page 155.

Summary of changes xvii

– A new API was added. See “Change Aggregate Attributes” on page 249. This API is accessed via anew subcommand opcode (160). See the table on summary of APIs for pfsctl in “pfsctl (BPX1PCT)”on page 240.

• With appropriate authority, a system programmer can initiate an online salvage of a zFS aggregate inorder to repair a damaged file system while the file system is still mounted.

– A new command, zfsadm salvage, was introduced. See “zfsadm salvage” on page 220.– A new API was added. See “Salvage Aggregate” on page 341. This API is accessed by means of a new

subcommand opcode (155). See the table on summary of APIs for pfsctl in “pfsctl (BPX1PCT)” onpage 240.

• The zfsadm commands have a new option, -trace. The privilege section for these commands wasupdated because READ access is no longer needed to the IOEFSPRM data set.

• zFS can record file system events, performance data, and per-file system statistics n the SystemManagement Facility (SMF). See “Using SMF records to report on activities ” on page 89. A new option,-smf_recording, was added to two commands.

– “zfsadm config” on page 160– “zfsadm configquery” on page 165

The smf_recording processing option was added to the IOEFSPRM configuration file. See “IOEFSPRM”on page 227.

• These sections were updated to include information about the new bpxwmigf shell command.

– Chapter 7, “Migrating data from HFS or zFS to zFS,” on page 63– “Using the z/OS HFS to zFS migration tool” on page 63

Changed

• With APAR OA55616, the AGGRFULL and FSFULL descriptions were updated in these sections:

– “MOUNT” on page 140– “IOEFSPRM” on page 227

• In “zfsadm fileinfo” on page 186, compressed # saved was changed to compress-eligible #saved.

• Corrected the pax example in “Without using an intermediate archive file” on page 64.• “The encryption process” on page 33 was updated with the following information:

– Decryption is supported. However, the decryption process does not remove key labels. File systemsthat have had key labels assigned cannot be mounted on a release prior to V2R3, even if those filesystems have not been encrypted or are currently not encrypted. Therefore, if there is no zFS systemin the shared file system environment that is eligible to own a file system with a key label assigned toit, the file system will be inaccessible.

– If you must back out to a release that is prior to V2R3, any file systems that are encrypted or have keylabels assigned to them cannot be owned on a system running the prior release. You may also need toback out the file system by taking one of the following actions:

- Restore a version of the file system that was backed up prior to encrypting it or assigning a key labelto it.

- Create a new file system that does not have a key label assigned to it and follow the migrationprocedures in Chapter 7, “Migrating data from HFS or zFS to zFS,” on page 63.

• “Encrypting existing file system data” on page 35 was updated with the following important note:Before an existing file system has a key label assigned to it, or is encrypted for the first time, do a fullbackup of the file system.

• “The compression process” on page 36 was updated with the following restriction: Compressed filesystems cannot be mounted on a release prior to V2R3. Therefore, if there is no zFS system in the

xviii z/OS: Distributed File Service zFS Administration

shared file system environment that is eligible to own a compressed file system, the file system will beinaccessible.

• These changes were made for APAR OA54472:

– “zFS installation and configuration steps” on page 11 was updated.– A reminder to take ICSF into consideration when enabling encryption was added. See “Encrypting

and compressing zFS file system data” on page 32.– The zfsadm chaggr command was updated to indicate that The -aggrfull, -aggrgrow, -rwshare, and -

norwshare options are mutually exclusive. See “zfsadm chaggr” on page 155.– For zsfadm fileinfo, the partially encrypted field was updated to include an explanation

that the completion percentage is displayed for large files. The partially decrypted field wasadded. See “zfsadm fileinfo” on page 186.

– For the List File Information API, fo_CEprogress in the Format section was updated to include onlyencryption and decryption. See “List File Information” on page 304.

– Clarification was added to indicate that COMPRESS is part of the LFS report. “LFS” on page 74contains the updated LFS report.

– “zFS installation and configuration steps” on page 11 was updated to indicate that the DFS user ID(or the OMVS user ID, if running in the OMVS address space) must have at least READ access to anyCSFKEYS and CSFSERV profiles for encrypted aggregates.

– A new usage note was added to zfsadm encrypt. See “zfsadm encrypt” on page 183.– Usage notes were added to zfsadm shrink. See “zfsadm shrink” on page 222.

• This change was made for APAR OA54416:

– The values for the long_cmd_thread option in the configuration option file were changed. The allowedrange for the foreground threads is now 1-3. The default number of foreground threads is now 1. See“IOEFSPRM” on page 227.

• Prior to V2R3, user data was kept in data spaces. In V2R3, the data is now kept in chunks of memorycalled cache spaces.

• Privileged users can no longer format without at least UPDATE access to the VSAM linear data set.Privileged users are those who are either UID 0 or have READ authority to theSUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIIXPRIV class. Various updates have been madeto reflect this change.

• Release updates were made to the service levels. See “Determining service levels” on page 94.• The default for the romount_recovery option for the IOEFSPRM configuration file was changed from OFF

to ON. See “IOEFSPRM” on page 227.• The default of the format_aggrversion option was changed from 4 to 5.• The default of the change_aggrversion_on_mount option was changed from OFF to ON.• The zfsadm fsinfo and MODIFY FSINFO commands have new owner status values, new selection

criteria, and a progress indicator for long-running administrative options.• The F ZFS,QUERY,KNPFS output was updated. See “KN” on page 72.• In V2R2, APAR OA49516 was made available. When applied, zFS ownership movement could be

controlled by using the honor_syslist option in IOEFSPRM. The honor_syslist option could bedynamically queried and changed with zfsadm config and zfsadm configquery.

• – “Dynamic movement of the zFS owner” on page 54 was updated to indicate that zFS always usesthe AUTOMOVE specification to limit zFS ownership to a subset of sysplex members.

– “IOEFSPRM” on page 227 was updated to indicate that the honor_syslist is no longer supported. If itis specified, it is accepted but not used.

– “zfsadm config” on page 160 was updated to indicate that the -honor_syslist option is no longersupported. If it is specified, it is accepted but not used.

– “zfsadm configquery” on page 165 was updated to indicate that the -honor_syslist option is no longersupported. If it is specified, it is accepted but not used.

Summary of changes xix

– “zfsadm attach” on page 152 was updated to indicate that the command will be removed in a futurerelease

• These APIs were updated to return 8-bit time stamp values:

– “List Attached Aggregate Names (Version 1)” on page 283– “List Aggregate Status (Version 2)” on page 276

• The descriptions of certain field names were changed for the List Aggregate Status (Version 2) API. See“List Aggregate Status (Version 2)” on page 276.

• The authorization level was changed from ALTER to UPDATE.

– “ioeagfmt” on page 118– “ioefsutl format” on page 132– “zfsadm format” on page 192– “Format Aggregate ” on page 266

• LINEAR was replaced by ZFS in the sample job to create and format a version 1.4 aggregate. See theExamples section in “ioefsutl format” on page 132.

Deleted

The zfsspace, largedir.pl, and auditid utilities are no longer available. Information about them has beendeleted.

Summary of changes for zFS for z/OS Version 2 Release 2 (V2R2)

New

• “What's new or changed for zFS in z/OS V2R2” on page 7 was added.• zFS can be run in the OMVS address space, which is used by z/OS UNIX. See “zFS running in the z/OS

UNIX address space” on page 16.• You can display detailed information about the zFS file system. See “Usage notes for displaying file

system information” on page 112 and “Examples of displaying file system information” on page 114.• MODIFY ZFS PROCESS has a new parameter, fsinfo, which displays detailed information about zFS file

systems. Usage notes and examples for displaying file system information were also added. See“MODIFY ZFS PROCESS” on page 108.

• The zfsadm config and zfsadm configquery commands have a new option, -modify_cmd_threads. It specifies the current number of threads that are defined to handle zFS modifycommands. See “zfsadm config” on page 160 and“zfsadm configquery” on page 165 .

• The zfsadm fsinfo command displays detailed information about zFS file systems. See “zfsadmfsinfo” on page 195.

• New reports are available that can be printed with the zfsadm query command using the keywords -stkm, -ctkc, and -svi. This information is also available in new application programming interfaces forClient Token Caching Component, Server Token Manager, and Statistics from the Server VnodeInterface. For more information about the keywords, see “zfsadm query” on page 213.

• The IOEFSPRM configuration options file has new options.

– The modify_cmd_threads option controls the number of modify commands that are runningsimultaneously.

– The user_running_hangdump option specifies whether a hang dump should be taken for a user taskthat has been hanging for approximately 5 minutes.

– The quiesceinfo_message_delay option specifies the minimum number of seconds to delay issuingthe IOEZ00830E message. See “Processing options for IOEFSPRM and IOEPRMxx” on page 229.

xx z/OS: Distributed File Service zFS Administration

• The pfsctl (BPX1PCT) application programming interface was updated to include a new command,ZFSCALL_FSINFO. Two subcommands (query modify_cmd_threads and setmodify_cmd_threads) were added to ZFSCALL_CONFIG. See Table 19 on page 242.

• These application programming interfaces (APIs) were added:

– “List Detailed File System Information” on page 290. It lists detailed file or directory information.– “Statistics Server Token Management Information” on page 408. It returns statistics for the server

token manager.– “Statistics Sysplex Client Operations Information” on page 423. It returns information about the

number of local operations that required the sending of a message to another system.– “Statistics Sysplex Owner Operations Information” on page 429. It returns information about the

number of calls that are processed on the local system as a result of a message that was sent fromanother system.

Changed

• Information about updating required APARs was updated for V2R2. See “Applying required APARs forz/OS V2R3” on page 14.

• zFS caches can now be obtained in virtual storage above the 2 GB bar (64-bit storage). As a result, muchlarger caches can be used to increase zFS performance. zFS performance can further be increasedbecause it can be run in the OMVS address space, which is used by z/OS UNIX. See “zFS running in thez/OS UNIX address space” on page 16.

• Clarification was added about the statistics that zFS supplies for SMF type 30 records. See “Support fortype 30 SMF record ” on page 46.

• "Performing a backup of zFS " was renamed to "Copying or performing a backup of a zFS" and a warningwas added. See Chapter 6, “Copying or performing a backup of a zFS,” on page 59.

• To handle the case of the source file system having symbolic links (or names) longer than 100characters, the pax examples in “Using an intermediate archive file” on page 64 and “Without using anintermediate archive file” on page 64 were updated to include the -o saveext option.

• Chapter 8, “Performance and debugging,” on page 65 was updated.• The QUERY,KN report was updated because the statistics report now allows for larger counter values to

be displayed. These displays will use a suffix indicating the multiplier that is to be used for the displayedcounter value. See “KN” on page 72.

• The LFS report was updated because large fast lookup statistics is no longer supported. See “LFS” onpage 74.

• Information about thrashing was added to the STKM report. See “STKM” on page 80.• The STOR report was updated. See “STOR” on page 81.• The VM report was updated because client caching is no longer supported. See “VM” on page 86.• Release updates were made to “Determining service levels” on page 94.• Starting in V2R2, zFS uses the enhanced log and enhanced status APIs XCF communication

protocol. Previously, it used the extended directory XCF communications protocol. For moreinformation, see “Determining the XCF protocol interface level” on page 94.

• The -client_cache_size and -tran_cache_size keywords for the zfsadm config and zfsadmconfigquery commands are no longer supported. If they are specified, they are accepted but notused.

• Various updates were made to the IOEFSPRM configuration options file.

– The client_cache_size option is now ignored because V1R12 can no longer exist in the sysplex.– The tran_cache_size option is now ignored because there is no longer a separate transaction cache.– The expected default value for the meta_cache_size and metaback_cache_size options were changed

because the entire calculated default for the size of the metadata cache is now assigned tometa_cache_size.

Summary of changes xxi

– The upper end of the expected value for token_cache_size was changed from 2621440 to 20 million.– The upper end of the expected value for meta_cache_size was changed from 1024 M to 64 G.– The upper end of the expected value for trace_table_size and xcf_trace_table_size were changed

from 2048 M to 65535 M.– The upper end of the expected value for vnode_cache_size was changed from 500000 to 10 million.

See “IOEFSPRM” on page 227.• The APIs in Chapter 13, “zFS application programming interface information,” on page 239 were

reformatted. One of the changes was that long was changed to int because the length of a long canbe 4 bytes or 8 bytes, depending on compiler options.

• The pfsctl (BPX1PCT) application programming interface was updated to include a new command,ZFSCALL_FSINFO. See “pfsctl (BPX1PCT)” on page 240.

• The Statistics Log Cache Information format was changed because a new log cache facility is used inV2R2. New statistics are returned pertaining to this new logging method. See “Statistics Log CacheInformation” on page 393.

• Statistics Storage Information returns information for storage above the 2 G addressing bar. See“Statistics Storage Information” on page 413.

• The Statistics Transaction Cache Information is no longer used, but documentation about it was kept.See “Statistics Transaction Cache Information” on page 435.

Deleted

• The section "Transaction cache" in Chapter 8, “Performance and debugging,” on page 65 was deletedbecause a separate transaction cache no longer exists.

• The flc IOEPRMxx configuration option was deleted because it is no longer supported.• The Delete File System API was deleted because it is no longer supported.• The sections "zFS support for read/write non-sysplex aware mounted file system" and "zFS support for

read/write sysplex aware mounted file system" were deleted because they described how zFS in V1R11or V1R12 systems handled read/write file systems. These systems can no longer exist in the sysplexwith V2R2.

• The section "Disabled aggregates when there are no z/OS V1R13 or later systems" was deleted becauseall systems must now be at z/OS V1R13 or later.

• The description of the IOEFSPRM configuration file option client_cache_size was deleted becauseV1R12 can no longer exist in the sysplex.

• The description of the IOEFSPRM configuration file option tran_cache_size was deleted because thenew zFS aggregate metadata logging method does not require a transaction cache.

• Information about large fast lookup statistics was deleted because it is no longer supported.• Information about large FLC processing was deleted because it is no longer supported.

z/OS Version 2 Release 1 summary of changesSee the Version 2 Release 1 (V2R1) versions of the following publications for all enhancements related toz/OS V2R1:

• z/OS Migration• z/OS Planning for Installation• z/OS Summary of Message and Interface Changes• z/OS Introduction and Release Guide

xxii z/OS: Distributed File Service zFS Administration

Part 1. zFS administration guideThis part of the document discusses guidance information for the z/OS File System (zFS).

• Chapter 1, “Overview of the zFS File System,” on page 3• Chapter 2, “Installing and configuring zFS,” on page 11• Chapter 3, “Managing zFS processes,” on page 19• Chapter 4, “Creating and managing zFS file systems using compatibility mode aggregates,” on page 21• Chapter 5, “Using zFS in a shared file system environment,” on page 49• Chapter 6, “Copying or performing a backup of a zFS,” on page 59• Chapter 7, “Migrating data from HFS or zFS to zFS,” on page 63• Chapter 8, “Performance and debugging,” on page 65• Chapter 9, “Overview of the zFS audit identifier,” on page 103

© Copyright IBM Corp. 2001, 2019 1

2 z/OS: Distributed File Service zFS Administration

Chapter 1. Overview of the zFS File System

z/OS Distributed File Service z/OS File System (zFS) is a z/OS UNIX System Services (z/OS UNIX) filesystem that can be used in addition to the hierarchical file system (HFS). zFS file systems contain files anddirectories that can be accessed with z/OS UNIX application programming interfaces (APIs). These filesystems can support access control lists (ACLs). zFS file systems can be mounted into the z/OS UNIXhierarchy along with other local (or remote) file system types (for example, HFS, TFS, AUTOMNT, andNFS).

zFS can be used for all levels of the z/OS UNIX System Services hierarchy (including the root file system).Because zFS has higher performance characteristics than HFS and is the strategic file system, HFS mightnot be supported in any future releases, which will cause you to migrate the remaining HFS file systems tozFS.

zFS can run sysplex-aware for read/write mounted file systems and for read-only mounted file systems.For more information, see “Terminology and concepts” on page 4, “Specifying zFS file systems assysplex-aware” on page 14, and Chapter 5, “Using zFS in a shared file system environment,” on page49.

Beginning with z/OS V1R13, zFS has enhanced its sysplex-aware support. For many file operations, zFScan now directly access zFS read/write mounted file systems in a shared file system environment fromzFS client systems. In z/OS V1R13 and later releases, when zFS runs in a shared file system environment,zFS always runs sysplex-aware on a file system basis (sysplex=filesys). See “zFS-enhanced sysplex-aware support” on page 51 for more information.

zFS and HFS can both participate in a shared sysplex. 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 and the Common Criteria for more information about multilevelsecurity and migrating your HFS version root to a zFS version root with security labels.

Notes:

1. Beginning with z/OS V2R1, zFS no longer supports multi-file system aggregates. If you have data thatis stored in zFS multi-file system aggregates, copy that data from the zFS multi-file system aggregatefile systems into zFS compatibility mode aggregates. Because zFS multi-file system aggregates cannotbe mounted in z/OS V2R1, you must copy the data from any file systems that are contained in multi-file system aggregates into zFS compatibility mode file systems using a non-shared file systemenvironment on a system that is running a release prior to z/OS V2R1.

2. Beginning with z/OS V2R1, zFS no longer supports clones. If you have read-only clone (.bak) filesystems, you should delete them using the zfsadm delete command on a system that is running arelease prior to z/OS V2R2.

3. Beginning with z/OS V2R2, zFS will only allow aggregates that contain exactly one file system in it to beattached.

FeatureszFS provides many features and benefits, which are described in the following sections:

PerformancezFS provides significant performance gains in many customer environments. zFS provides additionalperformance improvements when running sysplex-aware in a shared file system environment.

RestartzFS reduces the exposure to loss of updates. zFS writes data blocks asynchronously and does not waitfor 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.

© Copyright IBM Corp. 2001, 2019 3

Aggregate movementAs a part of supporting read/write mounted file systems that are accessed as sysplex-aware, zFSautomatically moves zFS ownership of a zFS file system to the system that has the most read/writeactivity. This system must also satisfy the restrictions that are imposed by the automove mountoptions for the file system. “Terminology and concepts” on page 4 has an explanation of z/OS UNIXfile system ownership and zFS file system ownership. Chapter 5, “Using zFS in a shared file systemenvironment,” on page 49 contains details.

Terminology and conceptsTo present all the benefits and details of zFS administration, the following concepts and terminology areintroduced:

AttachWhen a zFS file system is mounted, the data set is also attached. Attach means that zFS allocates andopens the data set. This attach occurs the first time a file system contained in the data set is mounted.

A zFS data set can also be attached (by issuing the zfsadm attach command) without mounting it.Beginning in z/OS V2R2, only zFS data sets that contain exactly one file system are allowed to beattached. However, there are many restrictions in this case. For example, the zFS data set would notbe available to z/OS UNIX applications because it was not mounted. In a shared file systemenvironment, the zFS data set would be detached, not moved, if the system went down or zFSinternally restarted. You might attach a zFS data set to explicitly grow it (zfsadm grow) or todetermine the free space available (zfsadm aggrinfo). You must detach the zFS data set (zfsadmdetach) before mounting it.

Catch-up mountWhen a file system mount is successful on a system in a shared file system environment, z/OS UNIXautomatically issues a corresponding local mount, which is called a catch-up mount, to every othersystem's PFS for a zFS read/write mounted file system that is mounted RWSHARE or for a read-onlymounted file system.

If the corresponding local mount is successful, z/OS UNIX does not function ship from that system tothe z/OS UNIX owning system when that file system is accessed. Rather, the file request is sentdirectly to the local PFS. This is sometimes referred to as Client=N, as indicated by the output of the DOMVS,F operator command, or df -v shell command. If the corresponding local mount isunsuccessful (for instance, DASD is not accessible from that system), z/OS UNIX function shipsrequests to the z/OS UNIX owning system when that file system is accessed (message BPXF221Imight be issued). This is sometimes referred to as Client=Y, as indicated by the output of the DOMVS,F or df -v commands. For examples of the command output, see “Determining the file systemowner” on page 52.

File system ownershipIBM defines a file system owner as the system that coordinates sysplex activity for a particular filesystem. In a shared file system environment, there is also the concept of file system ownership. Theowner of a file system is the first system that processes the mount. This system always accesses thefile system locally; that is, the system does not access the file system through a remote system. Othernon-owning systems in the sysplex access the file system either locally or through the remote owningsystem, depending on the PFS and the mount mode.

The file system owner is the system to which file requests are forwarded when the file system ismounted non-sysplex aware. Having the appropriate owner is important for performance when the filesystem is mounted read/write and non-sysplex aware. The term z/OS UNIX file system owner refers tothe owner of the zFS file system as z/OS UNIX recognizes it. This is typically the system where the filesystem is first mounted, but it can differ from the zFS file system owner (see zFS file system owner).zFS file system owner

zFS has its own concept of file system ownership, called the zFS file system owner. This is alsotypically the system where the file system is first mounted in a sysplex-aware environment. Filerequests to sysplex-aware file systems are sent directly to the local zFS PFS, rather than being


forwarded to the z/OS UNIX file system owner. This concept is shown in Figure 1 on page 5. Thelocal zFS PFS forwards the request to the zFS file system owner, if necessary. The z/OS UNIX filesystem owner can be different from the zFS file system owner. (In reality, zFS owns aggregates.Generally, we simplify this to say zFS file system owner because zFS compatibility modeaggregates only have a single file system.)

z/OS UNIX file system ownerThe term z/OS UNIX file system owner refers to the owner of the zFS file system as z/OS UNIXknows it. This is typically the system where the file system is first mounted.

For details about sysplex considerations and the shared file system environment, see “Determiningthe file system owner” on page 52 and Chapter 5, “Using zFS in a shared file system environment,”on page 49.

z/OS UNIX

zFS

z/OS UNIX

zFS

z/OS UNIX

zFS

z/OS UNIX

zFSzFS

z/OS UNIX

zFSzFS

cache

z/OS UNIX

zFSzFS

cache

zFS read/write file system mounted with NORWSHARE zFS read/write file system mounted with RWSHARE

z/OS UNIXapplication






Figure 1: z/OS UNIX and zFS file system ownership

When a file system is not sysplex-aware (that is, mounted as NORWSHARE), file requests are function-shipped by z/OS UNIX to the z/OS UNIX file system owner, and then to the PFS. When a file system issysplex-aware (that is, mounted as RWSHARE), file requests are sent directly to the local zFS PFS andthen function-shipped by zFS to the zFS file system owner, if necessary.

Function shippingFunction shipping means that a request is forwarded to the owning system and the response isreturned to the requestor through XCF communications.

Local mountA local mount means that z/OS UNIX issues a successful mount to the local PFS, which in this case iszFS. z/OS UNIX does this when either the file system is mounted sysplex-aware for that mode (read/write or read-only) or the system is the z/OS UNIX owner. When a file system is locally mounted on thesystem, z/OS UNIX does not function ship requests to the z/OS UNIX owning system. To determine if asystem has a local mount, see “Determining the file system owner” on page 52.

Non-sysplex aware (sysplex-unaware)A file system is non-sysplex aware (or sysplex-unaware) if the PFS (Physical File System) supportingthat file system requires it to be accessed through the remote owning system from all other systemsin a sysplex (allowing only one connection for update at a time) for a particular mode (read-only orread/write). The system that connects to the file system is called the file system owner. Othersystem's access is provided through XCF communication with the file system owner. For a non-sysplexaware zFS file system, file requests for read/write mounted file systems are function-shipped to theowning system by z/OS UNIX. The owning system is the only system where the file system is locallymounted and the only system that does I/O to the file system. See zFS file system owner and z/OSUNIX file system owner.

Overview of the zFS File System 5

OMVS address spaceThe address space used by z/OS UNIX, it runs a program that initializes the kernel. Starting in V2R2,zFS can be run in the OMVS address space.

Read-only file systemA file system that is mounted for read-only access is a read-only file system.

Read/write file systemA file system that is mounted for read and write access is a read/write file system.

Shared file system environmentThe shared file system environment refers to a sysplex that has a BPXPRMxx specification ofSYSPLEX(YES).

SysplexThe term sysplex as it applies to zFS, means a sysplex that supports the z/OS UNIX shared file systemenvironment. That is, a sysplex that has a BPXPRMxx specification of SYSPLEX(YES).

Sysplex-awarePertains to a physical file system that handles file requests for mounted file systems locally instead ofshipping function requests through z/OS UNIX.Sysplex-aware PFS

A physical file system (PFS), for example zFS, is sysplex-aware or non-sysplex aware for aparticular mount mode (read-only or read/write) in a shared file system environment. When it issysplex-aware, the PFS is capable of handling a local mount on the system that is not the z/OSUNIX owning system. The PFS that is sysplex-aware can avoid z/OS UNIX function shipping forthat mode. Both HFS and zFS file systems are always sysplex-aware for read-only mounts. HFS isalways non-sysplex aware for read/write mounts and always results in z/OS UNIX functionshipping from systems that are not the z/OS UNIX owning system. As of z/OS V1R13, zFS alwaysruns sysplex-aware (SYSPLEX=FILESYS) in a shared file system environment. Individual filesystems can be non-sysplex aware or sysplex-aware, with the default being non-sysplex aware.

Sysplex-aware file systemA file system can be mounted sysplex-aware or non-sysplex aware. When a file system is mountedsysplex-aware, it means that the file system is locally mounted on every system (when the PFS iscapable of handling a local mount on every system - that is, the PFS is running sysplex-aware) andtherefore, file requests are handled by the local PFS. All read-only mounted file systems arealways mounted sysplex-aware (see Figure 12 on page 50). HFS read/write mounted file systemsare always mounted non-sysplex aware. This means that file requests from non z/OS UNIX owningsystems are always function-shipped by z/OS UNIX to the z/OS UNIX owning system where thefile 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-awareor or non-sysplex aware.

zFS address spaceBecause zFS can run in its own colony address space or inside the OMVS address space, which is theaddress space used by z/OS UNIX, any reference to the zFS address space will mean the addressspace in which zFS is running.

zFS aggregateThe data set that contains a zFS file system is called a zFS aggregate. A zFS aggregate is a VirtualStorage Access Method (VSAM) linear data set. After the zFS aggregate is defined and formatted, azFS file system is created in the aggregate. In addition to the file system, a zFS aggregate contains alog file and a bitmap describing the free space. A zFS aggregate has a single read/write zFS file systemand is sometimes called a compatibility mode aggregate. Compatibility mode aggregates are similar toHFS.

Restriction: zFS does not support the use of a striped VSAM linear data set as a zFS aggregate. If youattempt to mount a compatibility mode file system that had previously been formatted and is a stripedVSAM linear data set, it will only mount as read-only. zFS does not support a zFS aggregate that hasguaranteed space.


zFS file systemRefers to a hierarchical organization of files and directories that has a root directory and can bemounted into the z/OS UNIX hierarchy. zFS file systems are located on DASD.

zFS Physical File System (PFS)Refers to the code that runs in the zFS address space. The zFS PFS can handle many users accessingmany zFS file systems at the same time.

ZFS PROCThe PROC that is used to start ZFS. It is typically called ZFS. If ZFS is running in the OMVS addressspace, then this refers to the OMVS PROC.

What's new or changed for zFS in z/OS V2R3A new zfsadm shrink command makes zFS aggregates smaller. Unused free space can be releasedfrom existing aggregates to more efficiently use DASD space.

User data in zFS file systems can be encrypted, compressed, or both. This provides additional securityand the ability for files to be stored on disk in a compressed format that requires less space.

Some attributes assigned to file systems when the are mounted can be dynamically changed using thezfsadm chaggr command without having to unmount and remount the file system.

A mounted file system can be verified by an online salvage utility. The file system can also be repaired, ifneeded. The online salvage is done with the zfsadm salvage command.

zFS aggregates that are created using the new ZFS keyword on the IDCAMS DEFINE CLUSTER command,or the zfsadm define command, do not have to be formatted in a separate step prior to being mounted.zFS will automatically format them during mount. File systems formatted during mount will use defaultvalues for all of the formatting keywords.

New IOEFSPRM configuration options were added to supply global default values during formatting:

• -format_encryption• -format_compression• -format_perms

With z/OS V2R3, the zFS defaults for format_aggrversion and change_aggrversion_on_mount will favorthe creation of version 5 aggregates and the conversion of version 4 aggregates to version 5 at mounttime. Once an aggregate is at version 5, any new files or directories will also be version 5. For a convertedaggregate, the old files and directories will remain version 4. A version 5 aggregate can be converted backto version 4 by using the ioefsutl converttov4 batch utility if the limits of a version 4 aggregate havenot been exceeded. Note that Version 5 aggregates cannot be mounted on z/OS V1R13.

Health check ZFS_VERIFY_COMPRESSION_HEALTH was added. For more information about the healthcheck, see IBM Health Checker for z/OS User's Guide.

For information about interface changes in zFS, see “Summary of changes for zFS for z/OS Version 2Release 3 (V2R3) ” on page xvi.

What's new or changed for zFS in z/OS V2R2In z/OS V2R2, zFS caches were moved above the 2 G addressing bar to allow for the use of very large zFScaches. These IOEFSPRM configuration variables were changed to support the following ranges of values:

Variable Range of values

vnode_cache_size 1000 to 10000000

meta_cache_size 1 M to 64 G

token_cache_size 20480 to 20000000

Overview of the zFS File System 7

Variable Range of values

trace_table_size 1 M to 65535 M

xcf_trace_table_size 1 M to 65535 M

With the zFS caches above the 2-G addressing bar, zFS can now be run inside the OMVS address space.This change yields improved performance for each file or directory operation.

The metaback cache is no longer a separate cache in a data space. It is combined withmeta_cache_size into one single metadata cache. For simplicity and to avoid future confusion, updatethe IOEFSPRM configuration file to combine these two options and remove the metaback_cache_sizesetting from the file.

zFS performance counters were changed from 4 bytes to 8 bytes. This change allows for monitoring of zFSperformance over longer periods of time before the counters wrap. The counters are made available viathe zFS Statistics Application Programming Interfaces. This information is available in the zFS modify andzfsadm query command reports.

• New reports are available that can be printed with the zfsadm query command using the keywords -stkm, -ctkc, and -svi. This information is also available in new Application Programming Interfaces forClient Token Caching Component, Server Token Manager, and Statistics from the Server VnodeInterface. For more information about the keywords, see “zfsadm query” on page 213.

The zfsadm -storage report now contains information about storage usage above the 2 G bar.

The new zfsadm fsinfo command displays detailed information for one or more file systems. Filesystems can be specified with a specific name, or in a group by using a common prefix or common suffix.They can also be selected by specifying common attributes. Another way to obtain the detailedinformation is by using the new File System Information Application Programming Interface or themodify zfs,fsinfo command.

zFS is using a better performing method for handling the writing of records to the zFS aggregate log. Thenew logging method displays different statistics in the zfsadm query -logcache command and in theMODIFY ZFS,QUERY,LOG performance report. The Statistics Log Cache Information ApplicationProgramming Interface will also return new statistics pertaining to this new logging method.

Health checks ZOSMIGV1R13_ZFS_FILESYS and ZOSMIGREC_ZFS_RM_MULTIFS were removed, andCACHE_REMOVALS was added. For more information, see z/OS Migration.

For information about interface updates in V2R2, see “Summary of changes for zFS for z/OS Version 2Release 2 (V2R2)” on page xx.

What's new or changed for zFS in z/OS V2R1Beginning with z/OS V2R1, zFS no longer supports multi-file system aggregates and clones. As a result,the following zfsadm commands are no longer supported:

• zfsadm clone• zfsadm clonesys• zfsadm create• zfsadm lsquota• zfsadm rename• zfsadm setquota

The following options are no longer supported on zfsadm config:

• -fsgrow• -user_cache_readahead

The following options are no longer supported on zfsadm configquery:


• -auto_attach• -fsgrow• -user_cache_readahead

The following pfsctl subcommands are no longer supported:

• On the Aggregate command:

– Create File System• On the File System co

version 2 release 3 z/os - ibm...2019/03/28 · understanding delays and hangs in zfs using the zfs...

Documents