zfsadm fsinfo

Purpose

zfsadm fsinfo displays detailed information about a zFS file system, which is also known as a zFS aggregate.

Format

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

Options

-aggregate name
Specifies the name of the aggregate to be displayed. The aggregate name is not case-sensitive and is translated to uppercase. To specify multiple aggregates with similar names, use an asterisk (*) at the beginning, at the end, or both at the beginning and the end of name as a wildcard. If -aggregate name is specified with wildcards, the default display is -basic. Otherwise, the default display is -owner. See Usage notes for zfsadm fsinfo for more information.
-all
Displays information for all aggregates in the sysplex. It is the default when -aggregate and -path are not specified. The default information display will be as if -basic were specified.
-basic
Displays a line of basic file system information for each specified file system. This option is the default in the following situations:
  • The -all option is specified but -full, -owner, and -reset are not specified.
  • None of -aggregate, -all, -path, -full, -owner, and -reset options are specified.
  • The -sort and -exceptions options are specified and neither -full nor -owner is specified.
  • The -aggregate option is specified with one or more wildcards.
See Usage notes for zfsadm fsinfo for more information.
-exceptions
Displays information about any specified aggregate that is quiesced, disabled, had grow failures, is low on space or damaged. Any specified aggregate is also displayed if it has had XCF communication failures or an error because it ran out of space or when doing an I/O operation. This option cannot be specified with -reset, -path, -select and -aggregate with no wildcard in name. Information is displayed by default as if the -basic option were specified. See Usage notes for zfsadm fsinfo for more information.
-full
Displays information that is maintained by the system that owns each specified file system. See Table 3 for a description of the information that is displayed for the owner. It also displays information that is locally maintained by each system in the sysplex that has each specified file system locally mounted. For information about local statistics that are displayed when the -full option is specified, see Table 5.
-help
Prints the online help for this command. All other valid options that are specified with this option are ignored.
-level
Prints the level of the zfsadm command. This information is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.
-owner
Displays only information that is maintained by the system that owns each specified file system. This option is the default when -aggregate without wildcards is specified. See Usage notes for zfsadm fsinfo for more information.
-path path
Specifies the path name of a file or directory that is contained in the file system for which information is to be displayed. The path name is case-sensitive and can start with or without a slash (/). The default information display will be as if -owner were specified.
-reset
Resets zFS statistics that are related to each specified file system.
-select criteria
Displays each specified file system that matches the criteria. Information is displayed by default as if the -basic option were specified. The information that is displayed can also be sorted by using the -sort option.

To use this option, specify a selection criteria from Table 1.

This option cannot be specified with -exceptions, -reset, -path, and -aggregate with no wildcard in name. See Usage notes for zfsadm fsinfo for more information.

-sort sort_name
Specifies that the information displayed is to be sorted as specified by the value of sort_name. The default is sort by Name. This option cannot be specified with -reset. The valid sorting options are listed in Table 4.
-trace file_name
Specifies the name of the file that will have the trace records written into it. The trace file can be a z/OS UNIX file, an existing MVS sequential data set, or a member of either an existing partitioned data set (PDS) or partitioned data set extended (PDSE). Use this option only at the direction of IBM Support.

For information about preallocation instructions for debugging, see Step 5 (Optional) Preallocate data sets for debugging in zFS installation and configuration steps.

Because MVS data set names must be fully qualified, z/OS UNIX has special rules for specifying MVS data set names in the shell environment. For more information, see Specifying MVS data set names in the shell environment in z/OS UNIX System Services Command Reference.

Usage notes for zfsadm fsinfo

  1. The zfsadm fsinfo command displays detailed information about the specified file systems. Normally, file systems must be attached before this command can be used to display their information. However, when a specific aggregate name (with no wildcards) is specified, the file system does not need to be attached. You can use several methods to specify aggregates, based on their names, as follows:
    • -aggregate with an exact aggregate name. The aggregate name is not case-sensitive and is translated to uppercase.
    • -aggregate using a wildcard ('*') at the beginning of the name value to select aggregates with a common suffix.
    • -aggregate using a wildcard ('*') at the end of the name value to select aggregates with a common prefix.
    • -aggregate using a wildcard ('*') at the beginning and the end of the name value to select aggregates with both a common prefix and a common suffix.
    • -path with the path name of a file or directory in a zFS file system. Information for the file system that contains the file or directory is displayed.
    Tip: To ensure proper processing by the z/OS UNIX shell, put single quotation marks around the wildcard (*).

    The -all option selects all file systems that are attached in the sysplex. It is the default.

  2. The -owner option displays all available information for each specified file system from the zFS-owning system. The information is obtained via XCF communication with the owning system if the owning system is not the local system.
  3. Aggregates can be selected by use of the -select option. To use this option, specify a criteria from Table 1. You can specify more than one criteria by using a comma to separate them.
    Table 1. Criteria for selecting aggregates
    Value Shows aggregates that ...
    BK Contain files currently being backed up.
    CE Had XCF communication failures between client systems and owning systems. This result typically means that applications have gotten timeout errors.
    CO Are compressed or partially compressed.
    DA Are marked damaged by the zFS salvager.
    DI Are disabled for reading and writing.
    EN Are encrypted or partially encrypted.
    EP Are partially encrypted or partially compressed.
    GD Are disabled for dynamic grow.
    GF Have failed dynamic grow attempts.
    GR Are currently being grown.
    IE Have had disk I/0 errors.
    L Have less than 1 MB of free space, which means that increased XCF traffic is required for writing files.
    NC Are not compressed.
    NE Are not encrypted.
    NS Are mounted NORWSHARE.
    OV Contain extended (v5) directories that are using overflow pages.
    Q Are currently quiesced.
    RO Are mounted read-only.
    RQ Had application activity.
    RW Are mounted read/write.
    RS Are mounted RWSHARE.
    SE Have returned ENOSPC errors to applications.
    SH Are currently being shrunk.
    SL Are currently being salvaged.
    TH Have sysplex thrashing objects in them.
    V4 Are version 1.4.
    V5 Are version 1.5.
    V5D Are disabled for conversion to version 1.5.
    WR Had application write activity.
  4. Aggregates can be selected by using the -exceptions option. This option can be useful for identifying file systems that have encountered unexpected conditions, and might need attention. Unexpected conditions include I/O errors, XCF communication failures or being low on space. An aggregate can also be damaged, quiesced, or disabled.
  5. The -basic option displays the file system name, the zFS-owning system name, and file system status. Table 2 lists the values of the file system status. A Legend string is also displayed at the end of the output as a quick reference to show the definitions of the abbreviated status values.
  6. When you use the -owner option, the displayed information has the file system status as part of the output. The status field contains abbreviated values. For quick reference, these values are defined in a Legend string at the end of the output. The full definitions of these abbreviations are listed in Table 2.
    Table 2. Definitions of abbreviated values when the -basic or -owner options are specified
    Values Explanation
    BK The aggregate contains files that are currently being backed up.
    CE The aggregate had XCF communication failures (timeout errors) since the last statistics reset.
    CI The aggregate is partially compressed.
    CO The aggregate is compressed.
    DA The salvage operation considered the aggregate damaged and it has not been repaired yet.
    DC The aggregate is partially decompressed.
    DE The aggregate is partially decrypted.
    DI The aggregate is disabled for access.
    EI The aggregate is partially encrypted.
    EN The aggregate is encrypted.
    GD Dynamic grow was disabled. This value is set if an aggregate has the AGGRGROW attribute assigned to it but due to a dynamic grow failure will not attempt future dynamic grows until an explicit administrator grow command is issued against that file system.
    GF The aggregate had failed dynamic grow attempts.
    GR The aggregate is being grown.
    IE The aggregate had disk I/O errors since the last statistics reset.
    L The aggregate is low on space as defined by the zFS distributed bitmap reservation algorithms (less than 1 MB of free space left).
    NC The aggregate is not compressed.
    NE The aggregate is not encrypted.
    NM The aggregate is attached, but not mounted.
    NS The aggregate is mounted NORWSHARE, or the aggregate is attached.
    OV The aggregate has directories with overflow pages.
    Q The aggregate is quiesced.
    RO The aggregate is mounted in R/O mode.
    RQ The aggregate had application activity.
    RW The aggregate is mounted R/W.
    RS The aggregate is mounted RWSHARE.
    SE The aggregate ran out of space at some time since the last statistics reset.
    SH The aggregate is currently being shrunk.
    SL The aggregate is currently being salvaged.
    TH The aggregate has objects in the sysplex that are undergoing thrashing.
  7. The -owner option displays the statistics that are shown in Table 3.
    Table 3. Statistics displayed when the -owner option is specified
    Statistics Description
    Anode Table Size Total space that is occupied by the anode table in kilobytes, including indirect blocks.
    Audit Fid The auditfid that is used to represent the file system for SAF auditing.
    Backups Number of files that are being backed up.
    Backup File Space Space that is pinned on disk for files being backed up. These are blocks that have been freed but cannot be used for new files until the backup is complete.
    Bitmap Size Size of the bitmap file in kilobytes, including indirect blocks.
    Compress Progress Indicates whether the compress operation is running or stopped with the percentage completion. If the compress operation is running, it also shows the time of the day when the long-running compress command was started and its task ID.
    Connected Clients All client systems in the sysplex that have local mounts for a file system that is mounted RWSHARE.
    Converttov5 Indicates whether the file system has the CONVERTTOV5 attribute assigned to it. If the aggregate is version 1.4, or is version 1.5 and does not have the CONVERTTOV5 attribute assigned to it, the second value is n/a. If the aggregate has the CONVERTTOV5 attribute assigned to it, the second value indicates whether automatic conversion is enabled or disabled. One possible reason it could be disabled is that the aggregate was quiesced after this system assumed ownership of the file system.
    Decompress Progress Indicates whether the decompress operation is running or stopped with the percentage completion. If the decompress operation is running, it also shows the time of the day when the long-running decompress command was started and its task ID.
    Devno The z/OS UNIX device number for the mounted file system.
    Decrypt Progress Indicates whether the decrypt operation is running or stopped with the percentage completion. If the decrypt operation is running, it also shows the time of the day when the long-running decrypt command was started and its task ID.
    Encrypt Progress Indicates whether the encrypt operation is running or stopped with the percentage completion. If the encrypt operation is running, it also shows the time of the day when the long-running encrypt command was started and its task ID.
    Encrypt-Scrubbing Progress Indicates whether the scrubbing phases (clearing of unused disk space) is running or stopped with the percentage completion. If the encrypt operation is running, it also shows the time of the day when the long-running encrypt command was started and its task ID.
    File System Creation Time Time that the file system was last formatted.
    File System Grow Shows whether the Aggrgrow attribute is enabled (ON or OFF). It also shows the number of grows that were performed since this system assumed ownership of the file system.
    File System Objects The number of objects in the file system. The number includes files, directories, symbolic links, ACLs, and z/OS UNIX special files.
    Free 8K Blocks Number of free 8 K blocks.
    Free 1K Fragments Number of free fragments in partially allocated blocks.
    Last Grow Time The time that the file system was last grown (by command or dynamically) since this system assumed ownership of the file system.
    Log File Size Total space in kilobytes occupied by the log file, including indirect blocks.
    Overflow HighWater The highest number of overflow pages that were ever allocated on disk in extended (v5) directories.
    Overflow Pages The number of overflow pages that are allocated to extended (v5) directories.
    Owner The name of the system that currently owns the aggregate.
    Quiesce ASID ASID of the job that quiesced the aggregate.
    Quiesce Jobname Name of job that quiesced the aggregate.
    Quiesce System Name of the system where the application was running that quiesced the aggregate.
    Quiesce Time The time that the file system was last quiesced. For critical I/O operations, zFS sends I/O operations in parallel, up to the maximum number that the parallel access volume (PAV) device can handle concurrently.
    Revocation Wait Time The average time that it took to revoke tokens from clients.
    Salvage Progress Indicates that a salvage operation is running. It also shows the time of the day when the long-running salvage operation was started, its task ID, and which step of the salvage process is currently being performed.
    Shrink Progress Indicates that a shrink operation is running. It also shows the time of the day when the long-running shrink operation was started, its task ID, and which step of the shrink process is currently being performed.
    Size Size of the aggregate in kilobytes.
    Space Monitoring The threshold and increment for space monitoring. 0,0 is used to mean that there is no space monitoring in use for the file system.
    Statistics Reset Time Time that the owner statistics were last reset.
    Status The status of the aggregate as known by the owning system. The display is a subset of the information that is available in the -basic display because it shows only what the owner knows. The -basic display is a one-line summary for all chosen sysplex members.
    Thrash Resolutions The number of times the owner invoked the thrash resolution protocol (as opposed to the normal direct I/O protocol) to resolve sysplex contention of objects in the file system.
    Thrashing Objects The current number of sysplex thrashing objects in the file system at one time.
    Time of Ownership Time that the current owning system assumed ownership of the file system. That is, the time of its primary mount or when it last assumed ownership due to aggregate movement.
    Token Revocations The number of times the owner revoked tokens from other sysplex members, which means there was contention on an object and a callback had to be made to one or more clients.
    Version The version of the aggregate. For example, 1.4 or 1.5.
  8. Table 4 lists the sorting options when the -sort option is specified.
    Table 4. Sorting options when the -sort option is specified
    Sorting option Function
    Name Sort by file system name, in ascending order. This sorting option is the default.
    Requests Sort by the number of external requests that are made to the file system by user applications, in descending order. The most actively requested file systems are listed first.
    Response Sort by response time of requests to the file system, in descending order. The slower responding file systems are listed first.
  9. The -full option displays statistics for each specified file system from the zFS owning system and from each system in the sysplex that has it locally mounted. This is obtained via XCF communication with each system in the sysplex. The owning system statistics are described in Table 3. The local statistics are described in Table 5.
    Table 5. Local statistics displayed when the full option is specified
    Statistics Description
    Application Reads The number of read requests that were made by applications for files and directories in this file system.
    Application Writes The number of write requests that were made by applications for files or directories in this file system.
    Average The average task wait time when it had to wait for an I/O operation. This is the full wait time, including any queue wait time and device response time.
    Avg. Rd XCF Resp. Time The average response time for XCF read requests for objects on the owning system.
    Avg. Read Resp. Time The average response time for read requests that were made by applications for files or directories in this file system.
    Avg. Wr XCF Resp. Time The average response time for XCF write requests for objects on the owning system.
    Avg. Write Resp. Time The average response time for write requests that were made by applications for files or directories in this file system.
    Canceled Operations The number of times a task was asynchronously abended (forced or canceled) while accessing this file system.
    DDNAME The DDNAME for the data set allocation on this system.
    Disk IO Errors The number of disk I/O errors for disk I/O operations performed on this system.
    ENOSPC Errors The number of out of space (ENOSPC) errors that were seen by applications for this file system on this system.
    Kbytes The number of kilobytes read from the DASD volume for this system.
    LFS Held Vnodes The number of vnodes that the z/OS UNIX logical file system has allocated for the file system.
    Metadata Cache 8K Pages The number of 8 K pages in the metadata cache for this file system.
    Mount Time The time the file system was mounted on this system.
    Open objects Number of files or directories that are open.
    PAV The number of noncritical concurrent I/O operations that zFS will send to the DASD at one time for this DASD volume. For critical I/O operations, zFS will send I/O operations in parallel, up to the maximum number that the parallel access volume (PAV) device can handle concurrently. An I/O operation is deemed critical if a task is, or will be waiting on that I/O operation to complete.
    Quiesce Waiters YES if there are tasks that are waiting for the file system to be unquiesced. Otherwise, NO.
    Reads The number of disk reads to the DASD volume for this system.
    Read XCF Calls The number of XCF requests to read objects from the system that owns the file system. This will be zero (0) on the owning system.
    Statistics Reset Time The time that the statistics for the local file system were last reset.
    Tokens The number of tokens that are held for objects in the file system by the token manager.
    TOTALS The totals for all DASD volumes for the file system on this system.
    User Cache 4K Pages The number of 4 K pages in the user file cache for this file system.
    Vnodes Number of vnodes in memory for the file system.
    VOLSER The DASD VOLSER that the file system resides on.
    Waits The number of times a task had to wait for an I/O operation to complete for disk I/O operations on this system.
    Writes The number of disk writes to the DASD volume for this system.
    Write XCF Calls The number of XCF requests to write objects to the system that owns the file system. This will be zero (0) on the owning system.
    XCF Comm. Failures The number of XCF communication failures (for example, timeouts) on XCF requests made for this file system on this system.
  10. All times are in milliseconds. Large numbers are displayed using the following suffixes:
    t
    Multiply the shown value by 1,000,000,000.
    m
    Multiply the shown value by 1000000.
    t
    Multiply the shown value by 1000.
    tr
    Multiply the shown value by 1,000,000,000,000.
    K
    Multiply the shown value by 1024.
    M
    Multiply the shown value by 1048576.
  11. When you use the -owner option, the displayed file system status will indicate whether a long-running administrative operation is running on the aggregate. The statistics and legend sections will display status information about the current progress of the long operation. Also, you will see percentage complete indicators for certain steps of the long operation that are expected to occupy the bulk of the time in the operation. For more information about the overall processing of the long option, refer to the appropriate zfsadm command.

Privilege required

To use the -reset option, the issuer must be a root user (UID=0) or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.Otherwise, the issuer does not need special authorization.

Examples

  1. To display basic file system information for zFS aggregate PLEX.DCEIMGNK.FSINFO:
    zfsadm fsinfo -aggregate PLEX.DCEIMGNK.FSINFO -basic
    
    
    PLEX.DCEIMGNK.FSINFO.DCEIMGNJ RW,RS,Q,GF,GD,L,SE,NE,NC
    Legend: RW=Read-write, Q=Quiesced, GF=Grow failed, GD=AGGRGROW disabled 
            L=Low on space, RS=mounted RWSHARE, SE=Space errors reported 
            NE=Not encrypted, NC=Not compressed
  2. To display full file system status for zFS aggregate PLEX.DCEIMGNK.FSINFO:
    zfsadm fsinfo -aggregate PLEX.DCEIMGNK.FSINFO -full
    
    File System Name: PLEX.DCEIMGNK.FSINFO
    
      *** owner information ***
      Owner:               DCEIMGNJ        Converttov5:            ON,DISABLED
      Size:                336K            Free 8K Blocks:         23
      Free 1K Fragments:   0               Log File Size:          112K
      Bitmap Size:         8K              Anode Table Size:       8K
      File System Objects: 3               Version:                1.5
      Overflow Pages:      0               Overflow HighWater:     0
      Thrashing Objects:   0               Thrashing Resolution:   0
      Token Revocations:   0               Revocation Wait Time:   0
      Devno:               46              Space Monitoring:       0,0
      Quiescing System:    DCEIMGNJ        Quiescing Job Name:     SUIMGNJ
      Quiescor ASID:       x4C             File System Grow:       ON,0
      Status:              RW,RS,Q,GF,GD,L,SE
      Audit Fid:           00000000 00000000 0000
      Backups:             0               Backup File Space:      0K 
    
      File System Creation Time: Nov  5 15:15:54 2013
      Time of Ownership:         Nov  5 15:25:32 2013
      Statistics Reset Time:     Nov  5 15:25:32 2013
      Quiesce Time:              Nov  5 15:28:39 2013
      Last Grow Time:            n/a
    
      Connected Clients:   DCEIMGNK
    
    
    Legend: RW=Read-write, Q=Quiesced, GF=Grow failed, GD=Grow disabled
            L=Low on space, RS=mounted RWSHARE, SE=Space errors reported
            NE=Not encrypted, NC=Not compressed
    
      *** local data from system DCEIMGNJ (owner: DCEIMGNJ) ***
      Vnodes:              1               LFS Held Vnodes:         4
      Open Objects:        0               Tokens:                  3
      User Cache 4K Pages: 5               Metadata Cache 8K Pages: 6
      Application Reads:   167837          Avg. Read Resp. Time:    0.059
      Application Writes:  23460           Avg. Writes Resp. Time:  0.682
      Read XCF Calls:      0               Avg. Rd XCF Resp. Time:  0.000
      Write XCF Calls:     0               Avg. Wr XCF Resp. Time:  0.000
      ENOSPC Errors:       0               Disk IO Errors:          0
      XCF Comm. Failures:  0               Cancelled Operations:    0
    
      DDNAME:              SYS00004
      Mount Time:          Nov  6 09:46:44 2013
    
    VOLSER PAV    Reads      KBytes     Writes     KBytes     Waits    Average
    ______ ___ __________ __________ __________ __________ __________ _________
    CFC001   1         12         88      25767     304116      18796 1.032
    ______ ___ __________ __________ __________ __________ __________ _________
    TOTALS             12         88      25767     304116      18796 1.032
    
    
  3. To display the status of the file system owner by using a wildcard:
    zfsadm fsinfo -aggregate PLEX.DCEIMGNJ.FS'*'
    
    PLEX.DCEIMGNJ.FS1.                         DCEIMGNJ RW,NS,NE,NC
    PLEX.DCEIMGNJ.FS2                          DCEIMGNJ RW,RS,NE,NC
    PLEX.DCEIMGNJ.FS3                          DCEIMGNJ RW,NS,NE,NC
    PLEX.DCEIMGNJ.FS2                          DCEIMGNJ RW,RS,NE,NC
    PLEX.DCEIMGNJ.FS3                          DCEIMGNJ RW,NS,NE,NC
    Legend: RW=Read-write,NS=Mounted NORWSHARE,NE=Not encrypted
            NC=Not compressed,RS=Mounted RWSHARE 
  4. A job to obtain the file system information by using a wildcard:
    //USERIDA JOB ,'Zfsadm fsinfo',
    // CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
    //GETINFO EXEC PGM=IOEZADM,REGION=0M,
    // PARM=('fsinfo -aggregate PLEX.DCEIMGNJ.FS*')
    //SYSPRINT DD SYSOUT=H
    //STDOUT DD SYSOUT=H
    //STDERR DD SYSOUT=H
    //SYSUDUMP DD SYSOUT=H
    //CEEDUMP DD SYSOUT=H
    
    The following lines are possible output from the job:
    
    PLEX.DCEIMGNJ.FS1                          DCEIMGNJ RW,NS,NE,NC
    Legend: RW=Read-write,NS=Mounted NORWSHARE,NE=Not encrypted   
            NC=Not compressed 
  5. A job to obtain information for the file system that contains directory /u/userida/fs1:
    //USERIDA JOB ,'Zfsadm fsinfo',
    // CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
    //GETINFO EXEC PGM=IOEZADM,REGION=0M,
    // PARM=('/fsinfo -path /u/userida/fs1')
    //SYSPRINT DD SYSOUT=H
    //STDOUT DD SYSOUT=H
    //STDERR DD SYSOUT=H
    //SYSUDUMP DD SYSOUT=H
    //CEEDUMP DD SYSOUT=H
    
    The following lines are possible output from the job:
    
    PLEX.DCEIMGNJ.FS1.                         DCEIMGNJ RW,NS,NE,NC
    Legend: RW=Read-write,NS=Mounted NORWSHARE,NE=Not encrypted   
            NC=Not compressed 

Related information

Commands:
  • zfsadm aggrinfo
  • zfsadm lsaggr
  • zfsadm lsfs
Files:
  • IOEFSPRM
  • MODIFY ZFS PROCESS