PM61809: PAGENT DOES NOT GET NOTIFIED WHEN TCP/IP IS STARTED IF THE /TMP DIRECTORY IS IN A ZFS MOUNTED AS RWSHARE

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• When Pagent is started before TCPIP, Pagent is expected to get
  notified when the stack has initialized and install all active
  policies in the stack. If the /tmp directory is in sysplex aware
  zFS mounted as RWSHARE, the Pagent.tmp file fails to register
  causing policy files not to be installed without update.
  
  To verify whether or not the /tmp directory is in a sysplex
  aware zFS mounted as RWSHARE, issue the following MODIFY ZFS
  commands:
  
  1. F ZFS,QUERY,LEVEL
       Show the zFS default for sysplex awareness.
  
  2. F ZFS,QUERY,FILES
       Find the filesystem by name and display its flags to
       determine if it's SYSPLEX AWARE according to the 'S'
       flag among other flags.
  
  Additional Symptoms:
  Pagent logs show the following error message...
  
  Error Registering file '/tmp/TCPIP.Pagent.tmp', IPC msg type=9,
  token='0', rc=-1, errno=EDC5247I Operation not supported.
  (errno2=0x11800631), errno2=11800631
  

Local fix

• Restart Pagent after the stack has initialized or issue the
  MODIFY PAGENT,UPDATE command so that the policy file and
  rules may be updated in the stack
  

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of the IBM Communications Server   *
  *                 for z/OS Version 1 Release 13 IP:            *
  *                 Policy Agent                                 *
  ****************************************************************
  * PROBLEM DESCRIPTION: PAGENT fails to install policies when   *
  *                      TCPIP is started.  The /tmp directory   *
  *                      is in a sysplex aware zFS mounted as    *
  *                      RWSHARE.                                *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  PAGENT fails to install policies when TCPIP is started.  The
  /tmp directory is in a sysplex aware zFS mounted as RWSHARE.
  
  PAGENT (Policy Agent) creates a /tmp/tcpname.Pagent.tmp file for
  each stack defined on a TCPIMAGE statement.  PAGENT issues an
  __w_pioctl() to register for notification when the file is
  altered.  The TCP/IP stack updates the file at initialization
  time and the notification triggers PAGENT to install policies.
  
  The __w_pioctl() fails when the /tmp directory is in a sysplex
  aware zFS mounted as RWSHARE with -1, EDC5247I Operation not
  supported, 0x11800631.  PAGENT continues processing but the
  __w_pioctl() failure prevents the file update notification from
  being delivered.  When the TCP/IP stack is started PAGENT does
  not receive the file update notification that is needed to
  trigger the installation of policies.
  +-------------------------------------------------------------+
  + Please check our Communications Server for OS/390 homepages +
  + for common networking tips and fixes.  The URL for these    +
  + homepages can be found in Informational APAR II11334.       +
  +-------------------------------------------------------------+
  

Problem conclusion

• PAGENT has been amended to issue message EZD1590I when the
  __w_pioctl() registration request fails.  The errno and errnojr
  are included in the message text for diagnostic purposes.
  
  PAGENT has been updated to support /tmp/tcpname.Pagent.tmp as a
  symbolic link.  The __w_pioctl() will be issued against the
  target of the symbolic link when defined.  When /tmp resides in
  a read/write sysplex aware zFS a symbolic link can be created
  to a target that resides in an HFS file system or in a
  zFS file system that is not read/write sysplex aware to enable
  the update notification.
  
  Example:
   # ln -s /mydir/TCPIP.Pagent.link /tmp/TCPIP.Pagent.tmp
  
  
  ****************************************************************
  * FUNCTION AFFECTED: Communications Server TCP/IP (PM61809)    *
  *                     Policy Agent                             *
  ****************************************************************
  * DESCRIPTION      : Documentation updates                     *
  ****************************************************************
  * TIMING           : None                                      *
  ****************************************************************
  Title: z/OS V1R13.0 Comm Svr: IP Configuration Guide
  Document Number: SC31-8775-20
  Chapter:  Policy-based networking
  Section:  Starting and stopping the Policy Agent
  Subsection:  Other considerations when starting the Policy Agent
  Insert after the following:
    In this z/OS UNIX file, tcpname is the name of a TCP/IP stack
    from a TcpImage statement. During TCP/IP stack initialization,
    the TCP/IP stack will attempt to modify a file by this name
    to notify the Policy Agent that the stack has been
    reactivated.  This causes the Policy Agent to automatically
    attempt to reinstall the existing policies to this stack.
  Text to insert:
    When /tmp/tcpname.Pagent.tmp is located in a read/write
    sysplex aware zFS file system a symbolic link can be created
    to a file that resides in an HFS file system or in a zFS file
    system that is not read/write sysplex aware to enable the
    update notification.
  
    The following example uses the ln command to create a symbolic
    link to a file in /mydir, where /mydir resides in an HFS or a
    read-only zFS.
  
      ln -s /mydir/TCPIP.Pagent.link /tmp/TCPIP.Pagent.tmp
  
  ****************************************************************
  * FUNCTION AFFECTED: Communications Server TCP/IP (PM61809)    *
  *                     Policy Agent                             *
  ****************************************************************
  * DESCRIPTION      : Documentation updates                     *
  ****************************************************************
  * TIMING           : None                                      *
  ****************************************************************
  Title: z/OS V1R13.0 Comm Svr: IP Messages Volume 2 (EZB, EZD)
  Document Number: SC31-8784
  Chapter:  EZD1xxxx messages
  Add the following message:
  
  EZD1590I PAGENT UPDATE NOTIFICATION FAILED WITH RETURN CODE
           errno REASON CODE errnojr
  
  Explanation: This message is received when one of the
  following types of Policy Agent update notification fails:
  
  - Stack startup notification for a stack defined on the
    TcpImage statement.  See z/OS IP Configuration Reference
    TcpImage and PEPInstance statement for details.
  
  - If the Policy Agent is started with the  -i/I  option, update
    notification in real time for changes to local files (all
    configuration files).  See z/OS IP Configuration Reference
    Starting Policy Agent from the z/OS shell for details.
  
  errno - is the z/OS UNIX System Services return code. These
  return codes are listed and described in the return codes
  (errnos) information in z/OS UNIX System Services Messages and
  Codes.
  errnojr - is the hexadecimal z/OS UNIX System Services reason
  code. The format of the 4-byte reason code is explained in the
  introduction to the reason codes (errnojrs) information of the
  z/OS UNIX System Services Messages and Codes, where the reason
  codes are listed.
  
  Example:
  $HASP100 PAGENT   ON STCINRDR
  IEF695I START PAGENT   WITH JOBNAME PAGENT   IS ASSIGNED TO USER
          IBMUSER , GROUP SYS1
  $HASP373 PAGENT   STARTED
  IEF403I PAGENT - STARTED - TIME=09.54.14
  EZZ8431I PAGENT STARTING
  EZZ8432I PAGENT INITIALIZATION COMPLETE
  EZD1590I PAGENT UPDATE NOTIFICATION FAILED WITH RETURN CODE 247
           REASON CODE 11800631
  
  System Action: Processing continues without update notification
  with the following results:
  
  - If the Policy Agent does not get notified of starting stacks,
    then the stacks do not have their required policies.
  
  - If the Policy Agent does not get notified of updates to local
    configuration files, then new policies are not updated in real
    time.
  
  Operator Response: Contact the System Programmer.
  
  User Response: Not Applicable
  
  System Programmer Response: Look up the return code and reason
  code values for the proper action to take. Also examine the
  Policy Agent log file to determine the name of the files having
  the problem. An example of what you would need to look for in
  the Policy Agent log file is the following:
  
  SYSERR :004: plfm_update_event_register: Error Registering file
  '/tmp/TCPIP.Pagent.tmp', IPC msg type = 9, token = '0', rc=-1,
  errno (247) = EDC5247I Operation not supported., errno2=11800631
  
  Correct the problem and instruct the operator to restart the
  Policy Agent if you want update notification.
  
  When the registering file is of the form '/tmp/tcpname.Pagent.
  tmp' and the file is located in a read/write sysplex aware zFS
  file system a symbolic link can be created to a file that
  resides in an HFS file system or a zFS file system that is not
  read/write sysplex aware to enable the update notification.
  
  Problem Determination: See the system programmer response.
  
  Source: z/OS Communications Server TCP/IP: Policy Agent (PAGENT)
  
  Module: plfmmisc
  
  Routing Codes: 10
  
  Descriptor Codes: 12
  
  Automation: This message is written to the system console and
  syslog for the Policy Agent. You might want to automate on this
  message to determine when the Policy Agent is not providing
  update notification and take corrective action.
  
  * Cross Reference between External and Internal Names
  EZAPAMSM (PAGENTM )  EZAPAPSM (PLFMMISC)  EZAPAZPI (PZOSINIT)
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UK79235

Modules/Macros

• EZAPAMSM EZAPAPSM EZAPAZPI
  

Fix information

• Fixed component name

  TCP/IP V3 MVS

• Fixed component ID

  5655HAL00

Applicable component levels

• R1D0 PSY UK79235

     UP12/06/29 P F206

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.