zdsfs - Mount a z/OS DASD

Ubuntu 22.04 LTS LPAR mode z/VM guest KVM guest

Use the zdsfs command to mount z/OS DASDs as a Linux® file system.

The zdsfs file system translates the z/OS data sets, which are stored on the DASDs in records of arbitrary or even variable size, into Linux semantics.

Through the zdsfs file system, applications on Linux can read z/OS physical sequential data sets (PS) and partitioned data sets (PDS) on the DASD. In the Linux file system, physical sequential data sets are represented as files. Partitioned data sets are represented as directories that contain the PDS members as files. Other z/OS data set formats, such as extended format data sets or VSAM data sets, are not supported. zdsfs is optimized for sequential read access.

Attention:
  • Unless you use a z/OSMF REST server to access the DASD, set the DASDs offline in z/OS before you mount them in Linux, to avoid data inconsistencies.
  • Through the zdsfs file system, the whole DASDs are accessible to Linux, but the access is not controlled by z/OS auditing mechanisms.

    To avoid security problems, you might want to dedicate the z/OS DASDs only for providing data for Linux.

Per default, only the Linux user who mounts the zdsfs file system has access to it. Configure file access behavior by using the allow_other, default_permissions, umask, uid, and gid options.

Tip: If you want to grant a user group access to the zdsfs file system, mount it with the fuse options default_permissions, allow_other, and gid.

To unmount file systems that you mounted with zdsfs, you can use umount.

See z/OS DFSMS Using Data Sets, SC26-7410 for more information about z/OS data sets.

Controlling read access using a REST server

You can use a z/OSMF REST server to control access. A configuration file configures access to the REST server, see zdsfs configuration file.

Using a REST server, the DASD does not have to be offline for Linux to access it. The REST server also enables authorization checking and audit capabilities.

To authenticate with the REST server from Linux, use a .netrc file. The .netrc file must be in your home directory and contain an entry for the REST server. Example .netrc file:
machine example.com
login user
password secret
Before you begin:
  • The FUSE library must be installed on your system. Ubuntu Server installs this library for you by default. You can also obtain it from sourceforge at sourceforge.net/projects/fuse.
  • To access full ECKD tracks, the raw-track access mode of the DASD must be enabled.

    Make sure that the DASD is set offline when you enable the raw-track access mode.

  • The DASD must be online.
    Tip: You can use the chccwdev command to enable the raw-track access mode and set the device online afterward in one step.

    Unless you use a z/OSMF REST server to access the DASD, set the DASD offline in z/OS before you set it online in Linux.

  • You must have the appropriate read permissions for the device node.
  • To use a REST server for read access:
    • A z/OSMF REST server must be up and running in z/OS.
    • A user ID must exist in z/OS that is allowed to access the required data sets. This user's login credentials must be used for zdsfs.

zdsfs syntax

Read syntax diagramSkip visual syntax diagramzdsfs <zdsfs-options>  <fuse-options> -l <file-name> <node-list>  <mount-point>
where:
<zdsfs-options>
zdsfs-specific options.
-c <config_file>
provides a configuration file for zdsfs. The default is /etc/zdsfs.conf.
-o ignore_incomplete
represents all complete data sets in the file system, even if there are incomplete data sets. Incomplete data sets are not represented.

In z/OS, data sets might be distributed over different DASDs. For each incomplete data set, a warning message is issued to the standard error stream. If there are incomplete data sets and this option is not specified, the zdsfs command returns with an error.

-o rdw
keeps record descriptor words (RDWs) of data sets that are stored by using the z/OS concept of variable record lengths.
-o restapi
uses z/OSMF REST services for coordinated read-access to data sets. The user credentials are read from the .netrc file in the user's home directory, or from the location the NETRC environment variable points to.
-o restserver=<server_URL>
specifies up to three server URLs to z/OSMF REST services. If more than one server is specified, the first that responds is used.
-o tracks=<n>
specifies the track buffer size in tracks. The default is 128 tracks.

zdsfs allocates a track buffer of <n>*120 KB for each open file to store and extract the user data. Increasing the track buffer size might improve your system performance.

-o seekbuffer=<s>
sets the maximum seek history buffer size in bytes. The default is 1,048,576 B.

zdsfs saves offset information about a data set in the seek history buffer to speed up the performance of a seek operation.

-o check_host_count
checks the host-access open count to ensure that the device is not online to another operating system instance. The operation is canceled if another operating system instance is accessing the volume.
<fuse-options>
options for FUSE. The following options are supported by the zdsfs command. To use an option, it must also be supported by the version of FUSE that is installed.
-d or -o debug
enables debug output (implies -f).
-f
runs the command as a foreground operation.
-o allow_other
allows access to other users.
-o allow_root
allows access to root.
-o default_permissions
enables permission checking by the kernel.
-o max_read=<n>
sets maximum size of read requests.
-o kernel_cache
caches files in the kernel.
-o [no]auto_cache
enables or disables caching based on modification times.
-o umask=<mask>
sets file permissions (octal).
-o uid=<n>
sets the file owner.
-o gid=<n>
sets the file group.
-o max_write=<n>
sets the maximum size of write requests.
-o max_readahead=<n>
sets the maximum readahead value.
-o async_read
performs reads asynchronously (default).
-o sync_read
performs reads synchronously.
<node-list>
one or more device nodes for the DASDs, separated by blanks.
<file-name>
a file that contains a node list.
<mount-point>
the mount point in the Linux file system where you want to mount the z/OS data sets.
-h or --help
displays help information for the command. To view the man page, enter man zdsfs.
-v or --version
displays version information for the command.

File characteristics

There are two ways to handle the z/OS characteristics of a file:
  • The file metadata.txt:
    The metadata.txt file is in the root directory of the mount point. It contains one row for each file or directory, where:
    dsn
    specifies
    • the name of the file in the form <file-name> for z/OS physical sequential data sets.
    • the name of the directory in the form <directory-name>, and the name of a file in that directory in the form <directory-name>(<file-name>) for z/OS partitioned data sets.
    dsorg
    specifies the organization of the file. The organization is PO for a directory, and PS for a file.
    lrecl
    specifies the record length of the file.
    recfm
    specifies the z/OS record format of the file. Supported record formats are: V, F, U, B, S, A, and M.
    Example: 
    dsn=FOOBAR.TESTF.TXT,recfm=FB,lrecl=80,dsorg=PS
dsn=FOOBAR.TESTVB.TXT,recfm=VB,lrecl=100,dsorg=PS
dsn=FOOBAR.PDSF.DAT,recfm=F,lrecl=80,dsorg=PO
dsn=FOOBAR.PDSF.DAT(TEST1),recfm=F,lrecl=80,dsorg=PS
dsn=FOOBAR.PDSF.DAT(TEST2),recfm=F,lrecl=80,dsorg=PS
dsn=FOOBAR.PDSF.DAT(TEXT3),recfm=F,lrecl=80,dsorg=PS
  • Extended attributes:
    user.dsorg
    specifies the organization of the file.
    user.lrecl
    specifies the record length of the file.
    user.recfm
    specifies the z/OS record format of the file.
    You can use the following system calls to work with extended attributes:
    listxattr
    to list the current values of all extended attributes.
    getxattr
    to read the current value of a particular extended attribute.

    You can use these system calls through the getfattr command. For more information, see the man pages of these commands and of the listxattr and getxattr system calls.

Examples

  • To mount the z/OS DASD represented by the file node /dev/dasde and specifying a z/OSMF REST server for coordinated read-access:
    # zdsfs -o restapi -o restserver=zos1.server.tld/zosmf /dev/dasde /mnt
  • To mount disks with a REST server in place:
    # zdsfs /dev/disk/by-path/ccw-0.0.edc0 /dev/disk/by-path/ccw-0.0.edc7 /mnt/
Using z/OSMF REST services on https://example.com/zosmf/

    The mount process informs you of which REST server is used.

  • Enable the raw-track access mode of DASD device 0.0.7000 and set the device online afterward:
    # chccwdev -a raw_track_access=1 -e 0.0.7000
  • Mount the partitioned data set on the DASDs represented by the file nodes /dev/dasde and /dev/dasdf at /mnt: 
    # zdsfs /dev/dasde /dev/dasdf /mnt
  • As user myuser, mount the partitioned data set on the DASD represented by the file node /dev/dasde at /home/myuser/mntzos:
    • Access the mounted file system exclusively:
      # zdsfs /dev/dasde /home/myuser/mntzos
    • Allow the root user to access the mounted file system:
      # zdsfs -o allow_root /dev/dasde /home/myuser/mntzos
    The ls command does not reflect these permissions. In both cases, it shows:
    # ls -al /home/myuser/mntzos
total 121284
dr-xr-x--- 2 root   root          0 Dec  3 15:54 .
drwx------ 3 myuser myuser     4096 Dec  3 15:51 ..
-r--r----- 1 root   root    2833200 Jun 27  2012 EXPORT.BIN1.DAT
-r--r----- 1 root   root    2833200 Jun 27  2012 EXPORT.BIN2.DAT
-r--r----- 1 root   root    2833200 Jun 27  2012 EXPORT.BIN3.DAT
-r--r----- 1 root   root    2833200 Feb 14  2013 EXPORT.BIN4.DAT
dr-xr-x--- 2 root   root   13599360 Aug  9  2012 EXPORT.PDS1.DAT
dr-xr-x--- 2 root   root   13599360 Aug  9  2012 EXPORT.PDS2.DAT
dr-xr-x--- 2 root   root   13599360 Aug  9  2012 EXPORT.PDS3.DAT
dr-xr-x--- 2 root   root   55247400 Aug  9  2012 EXPORT.PDS4.DAT
-r--r----- 1 root   root        981 Dec  3 15:54 metadata.txt

$ ls -al /dev/dasde
brw-rw---- 1 root disk 94, 16 Dec  3 13:58 /dev/dasde
  • As root user, mount the partitioned data set on the DASD represented by the file node /dev/dasde at /mnt on behalf of the user ID myuser (UID=1002), and permit the members of the group ID zosimport (GID=1002) file access:
    # zdsfs /dev/dasde /mnt -o uid=1002,gid=1002,allow_other,default_permissions
    The ls command indicates the owner myuser and the access right for group zosimport:
    $ ls -al /mnt
total 121284
dr-xr-x---  2 myuser zosimport        0 Dec  3 14:22 .
drwxr-xr-x 23 root   root          4096 Dec  3 13:59 ..
-r--r-----  1 myuser zosimport      981 Dec  3 14:22 metadata.txt
-r--r-----  1 myuser zosimport  2833200 Jun 27  2012 EXPORT.BIN1.DAT
-r--r-----  1 myuser zosimport  2833200 Jun 27  2012 EXPORT.BIN2.DAT
-r--r-----  1 myuser zosimport  2833200 Feb 14  2013 EXPORT.BIN3.DAT
-r--r-----  1 myuser zosimport  2833200 Jun 27  2012 EXPORT.BIN4.DAT
dr-xr-x---  2 myuser zosimport 13599360 Aug  9  2012 EXPORT.PDS1.DAT
dr-xr-x---  2 myuser zosimport 13599360 Aug  9  2012 EXPORT.PDS2.DAT
dr-xr-x---  2 myuser zosimport 55247400 Aug  9  2012 EXPORT.PDS3.DAT
dr-xr-x---  2 myuser zosimport 13599360 Aug  9  2012 EXPORT.PDS4.DAT
  • Unmount the partitioned data set that is mounted at /mnt: 
    # fusermount -u /mnt
  • Show the extended attributes of a file, FB.XMP.TXT, on a z/OS DASD that is mounted on /mnt: 
    # getfattr -d /mnt/FB.XMP.TXT
  • Show the extended attributes of all files on a z/OS DASD that is mounted on /mnt: 
    # cat /mnt/metadata.txt

zdsfs configuration file

The default path to the zdsfs configuration file is /etc/zdsfs.conf. Specify a different configuration file location with the -c <config_file> option.

The configuration file can contain the following options:
restapi = 0 | 1
Enables (1) or disables (0) the use of z/OSMF REST services. If enabled, a valid REST server must be specified with the restserver= option, as well as a .netrc file with a valid z/OS user ID and password.
restserver = <URL>
Specifies the URL of the z/OSMF REST server that is used for coordinated read-access.

For failover scenarios: Optionally, provide up to three additional server addresses. These are tried in the specified order if one of the servers cannot be reached during mount. If a server is unresponsive during operation, all specified servers are probed again.

keepalive = <timeout_in_seconds>
Changes the keepalive timer for ENQs. By default the keepalive refreshes the access after 540 seconds (9 minutes). The 9 minutes are chosen to prevent a timeout by z/OS after 10 minutes.
An example of a zdsfs.conf file could look similar to the following:
# rest enabled
restapi = 1

# rest server
restserver = example.com/zosmf/

# backup rest server
restserver=https://example.com/zosmf/

# keepalive timeout in seconds (default 540)
keepalive = 540