zFS installation and configuration steps

To install, configure, and access zFS, you must perform the following administrative steps:

Install and perform postinstallation of Distributed File Service by following the applicable instructions in z/OS Program Directory or in ServerPac: Installing Your Order. Following is a summary of the information that is contained in those documents:
1. Ensure that the target and distribution libraries for Distributed File Service are available.
2. Run the prefix.SIOESAMP(IOEISMKD) job from UID 0 to create the symbolic links that are used by Distributed File Service. This job reads the member prefix.SIOESAMP(IOEMKDIR) to delete and create the symbolic links.
3. Ensure that the DDDEFS for Distributed File Service are defined by running the prefix.SIOESAMP(IOEISDDD) job.
4. Install the Load Library for Distributed File Service. The Load Library (hlq.SIEALNKE) must be APF-authorized and must be in link list.
5. Install the samples (hlq.SIOESAMP).
6. Install the sample PROC for ZFS (hlq.SIOEPROC).
7. One method of providing an IOEFSPRM configuration file is to define it as a data set with an IOEZPRM DD card. If zFS is to run in the OMVS address space, the IOEZPRM DD card should be placed in the OMVS PROC. If zFS is to run in its own colony address space, create a JCL PROC for the zFS started task in SYS1.PROCLIB by copying the sample PROC from the previous step.
  The DDNAME IOEZPRM identifies the optional zFS configuration file. Although this DD statement is optional, it is recommended that it be included to identify the parameter data set to be used for zFS. For now, it is suggested that this DD refer to a PDS with a member called IOEFSPRM that has a single line that begins with an asterisk (*) in column 1. Subsequent modifications can be made to the IOEFSPRM member, see IOEFSPRM.
  
  As the preferred alternative to the IOEZPRM DDNAME specification, delete the IOEZPRM DDNAME and use the IOEPRMxx parmlib member. In this case, the member has the name IOEPRMxx, where you specify xx in the parmlib member list. See IOEFSPRM for more information.
  
  To run zFS so that it is not under control of JES, see step 2. You might want to do this so that zFS does not interfere with shutting down JES.
8. Add the following RACF® commands:
```
ADDGROUP DFSGRP SUPGROUP(SYS1) OMVS(GID(2))
ADDUSER DFS OMVS(HOME(’/opt/dfslocal/home/dfscntl’) UID(0)) 
DFLTGRP(DFSGRP) AUTHORITY(USE)UACC(NONE)
RDEFINE STARTED DFS.** STDATA(USER(DFS))
RDEFINE STARTED ZFS.** STDATA(USER(DFS))
SETROPTS RACLIST(STARTED)
SETROPTS RACLIST(STARTED) REFRESH
```
  zFS specifies the DFS user ID in the preceding commands. A user ID other than DFS can be used to run the zFS started task if it is defined with the same RACF characteristics as shown for the DFS user ID. If zFS is to run in the OMVS address space, it will run under the OMVS user ID. For this reason, the OMVS user ID should be given the same RACF characteristics as the DFS user ID. The user ID that is used will be referred as the DFS user ID.
  
  The DFS user ID must have at least ALTER authority to all VSAM linear data sets that contain zFS aggregates.
  
  If there are encrypted zFS aggregates, the DFS user ID must also have at least READ access to any CSFKEYS profiles for aggregates that are encrypted. If ICSF is configured with CHECKAUTH(YES), the DFS user ID must also have at least READ access to the CSFKRR2 CSFSERV profile. For more information about the CSFKEYS and CSFSERV profiles and the encryption of data sets, see Data Set Encryption in z/OS DFSMS Using Data Sets.
  
  As an alternative to permitting the DFS user ID to all of the necessary security profiles, you can assign the zFS started task the TRUSTED attribute or you can assign the user ID of the zFS started task the OPERATIONS attribute.
Create a BPXPRMxx entry for zFS.
Add a FILESYSTYPE statement to your BPXPRMxx parmlib member:
```
FILESYSTYPE TYPE(ZFS)ENTRYPOINT(IOEFSCM) ASNAME(ZFS)
```
Specifying the ASNAME(ZFS) keyword causes zFS to run in its own colony address space. To have zFS run in the OMVS address space, omit the ASNAME keyword.
```
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
```
Recommendation: Specify KERNELSTACKS(ABOVE) when zFS is running in the OMVS address space.
Update your IEASYSxx parmlib member to contain the OMVS=(xx,yy) parameter for future IPLs.
If necessary, you can specify that zFS should not be only run under control of JES by including SUB=MSTR. For example:
```
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM) ASNAME(ZFS,'SUB=MSTR')
```
To use the IOEPRMxx parmlib members (mentioned in step 1.g), specify the xx values in the FILESYSTYPE statement for zFS as in the following example:
```
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM) ASNAME(ZFS,'SUB=MSTR') PARM('PRM=(01,02,03)')
```
In this case, you must not have an IOEZPRM DD statement in your ZFS PROC. Step 4 contains an explanation as to why you should not have an IOEZPRM DD. For more information about using IOEPRMxx, see IOEFSPRM.
Run the dfs_cpfiles program.
Running this program as described in z/OS Program Directory is recommended even if you plan to only use zFS support. The only zFS configuration file is the zFS configuration file, which is not created by the dfs_cpfiles program. But, to complete the installation of Distributed File Service, run the dfs_cpfiles program to create other files that are needed by the SMB server. This avoids problems if SMB is later activated.
To run the dfs_cpfiles program:
- Log on as root (UID 0) on the local z/OS® system.
- From the z/OS UNIX shell, enter /usr/lpp/dfs/global/scripts/dfs_cpfiles.
(Optional) Create or update the zFS configuration options file (IOEPRMxx, also known as IOEFSPRM).
The zFS configuration options file is optional. There are two methods to specify the zFS configuration options file: use IOEPRMxx in the parmlib or use an IOEZPRM DD statement in the PROC that is used to start the address space where zFS is running.
- As the preferred alternative to the IOEZPRM DD statement, the IOEFSPRM member can be specified as a true parmlib member. In this case, the member has the name IOEPRMxx, where xx is specified in the parmlib member list. You must omit the IOEZPRM DD statement in the PROC that is used to start the address space in which zFS will run. The IOEPRMxx configuration options file can be specified with no options contained in it. Options are only required if you want to override the default zFS options. As mentioned in step 1.g, it is recommended that you create an empty IOEPRMxx parmlib member. The IOEPRMxx member should only contain one line that is a comment (an asterisk (*) in column 1). See IOEFSPRM for more information.
- If you use the IOEZPRM DD statement, the PDS (organization PO) to which it points should have a record format of FB with a record length of 80. The block size can be any multiple of 80 that is appropriate for the device. A sample IOEFSPRM is provided in hlq.SIOESAMP(IOEFSPRM). IOEFSPRM is also known as IOEZS001. See IOEFSPRM for a description of the IOEFSPRM options. Update the IOEZPRM DD statement in the OMVS or ZFS PROC to contain the name of the IOEFSPRM member, as shown in the following example:
```
IOEZPRM DD DSN=SYS4.PVT.PARMLIB(IOEFSPRM),DISP=SHR
```
  If you are running a sysplex, you must have different zFS configuration files for different systems. Using zFS in a shared file system environment explains why different zFS configuration files are required. In this case, you should also specify a system qualifier in the data set name in the IOEZPRM DD, as shown in the following example:
```
IOEZPRM DD DSN=SYS4.&SYSNAME..PARMLIB(IOEFSPRM),DISP=SHR
```
(Optional) Preallocate data sets for debugging.
This step is optional because trace information is always available in the dump data set, and can be requested only by IBM® Service. If needed, allocate the zFS trace output data set as a PDSE with RECFM=VB, LRECL=133 with a primary allocation of at least 50 cylinders and a secondary allocation of 30 cylinders. The name of this trace output data set should be specified in the trace_dsn option in the IOEFSPRM file. Next, allocate a debug settings data set as a PDS member with an LRECL=80. Add one comment line in the member (use a /* followed by */). Specify the name of this debug settings data set member in the debug_settings_dsn option of the IOEFSPRM file. Perform this process for each member of the sysplex.
Create a zFS (compatibility mode) file system.
A zFS file system resides in a zFS aggregate. A zFS aggregate is a VSAM linear data set. See Creating and managing zFS file systems using compatibility mode aggregates for details on creating zFS file systems.

Beginning in z/OS V2R1, ioeagfmt fails if the zFS PFS is not active on the system.
Create a directory and mount the zFS file system on it.
You can create a directory with the z/OS UNIX mkdir command or you can use an existing directory. The TSO/E MOUNT command or the /usr/sbin/mount REXX exec can be used to mount the zFS file system on the directory. See Creating and managing zFS file systems using compatibility mode aggregates for details on mounting zFS file systems.

Note: Steps 6 and 7 can be repeated as many times as necessary for each permanently mounted zFS file system. Only step 6 is needed for zFS automounted file systems (assuming that the automount file system has been set up.)
Add mount statements to BPXPRMxx members to mount the zFS file systems on the next IPL.
For example:
```
MOUNT FILESYSTEM('OMVS.PRV.COMPAT.AGGR001') TYPE(ZFS) MOUNTPOINT('/etc/mountpt')
```

All MVS data sets that are specified in DD statements in the zFS PROC, in options in the IOEFSPRM configuration file, and in MOUNT statements in BPXPRMxx must be available at IPL time. If an MVS data set is migrated by hierarchical storage management (HSM), then the initialization of zFS might wait indefinitely for the data set recall. This hang on one system can lead to a sysplex-wide hang. Any ARC0055A message that is issued for the migrated data set will need a reply to prevent this hang.